# Handle verification updates

Help your connected accounts maintain compliance with changing verification requirements.

Before your connected accounts can accept payments and send payouts, you must fulfill what are typically called Know Your Customer (KYC) requirements. To do so, you must collect [certain information about your connected accounts](https://docs.stripe.com/connect/required-verification-information.md) and send it to Stripe for verification.

Stripe frequently updates KYC requirements, often due to changes implemented by financial regulators, card networks, and other financial institutions.

These updates might require you to take the following actions:

1. Modify your onboarding flow to account for the changed requirements.
1. Collect updated information from affected connected accounts and handle verification responses.
1. [Handle risk-related requirements](https://docs.stripe.com/connect/handling-api-verification.md) by notifying connected accounts of identified issues so you can guide them to resolve through Stripe interfaces.

When [upcoming requirements updates](https://support.stripe.com/user/questions/onboarding-requirements-updates) affect your connected accounts, we’ll notify you.

## Identify upcoming requirements 

When Stripe is responsible for collecting requirements ([controller.requirement_collection](https://docs.stripe.com/api/accounts/object.md#account_object-controller-requirement_collection) is `stripe`), Stripe handles upcoming requirement changes for your connected accounts automatically. In that case, the rest of this document doesn’t apply to your platform.

If the platform is responsible for collecting requirements (`requirement_collection` is `application`), you need to handle upcoming requirement changes yourself. Stripe surfaces these changes through the `future_requirements` hash, and how you address them depends on your onboarding integration type, as explained below.

Upcoming requirements appear in the `future_requirements` hashes of the [Account](https://docs.stripe.com/api/accounts/object.md#account_object-future_requirements) and [Capability](https://docs.stripe.com/api/capabilities/object.md#capability_object-future_requirements) objects. They don’t appear in the `requirements` hash, and don’t affect any capabilities.

When an upcoming requirement takes effect, it moves from the `future_requirements` hash to the `requirements` hash and can affect the account’s capabilities. That might prevent the account from conducting transactions until you fulfill the requirement. The `future_requirements.current_deadline` timestamp represents when entries in `future_requirements` will move to `requirements`.

## Collect future requirements 

If you haven’t already integrated with Stripe, configure your integration using the [design an integration guide](https://docs.stripe.com/connect/design-an-integration.md) before continuing.

How you collect future requirements depends on your onboarding integration type. When current or upcoming requirements change, Stripe automatically updates Stripe-hosted and embedded onboarding flows, while API-based flows require you to update them manually.

| Onboarding type          | How to collect future requirements                                                                                                                                                                                                                                                                                                                                                                               |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Stripe-hosted onboarding | When creating `AccountLinks`, set [collection_options.future_requirements](https://docs.stripe.com/api/account_links/create.md#create_account_link-collection_options) to ‘include’.                                                                                                                                                                                                                             |
| Embedded onboarding      | When you render the [account onboarding component](https://docs.stripe.com/connect/supported-embedded-components/account-onboarding.md) or [account management component](https://docs.stripe.com/connect/supported-embedded-components/account-management.md), use the collection options to set `future_requirements` to `include`.                                                                            |
| API-based onboarding     | Monitor the account’s `future_requirements` hash, update your onboarding flow to collect any new entries, and submit the information using the [Accounts](https://docs.stripe.com/api/accounts/update.md) or [Persons](https://docs.stripe.com/api/persons/update.md) API. See [detailed instructions](https://docs.stripe.com/connect/handle-verification-updates.md#integrate-with-future-requirements) below. |

If you use Stripe-hosted or embedded onboarding, you can instead collect required information by creating and sharing [remediation links](https://docs.stripe.com/connect/dashboard/remediation-links.md).

## Integrate with future requirements 

If you use Stripe-hosted or embedded onboarding, requirements changes don’t require you to update your onboarding flow. Skip to the section on [listening for updates](https://docs.stripe.com/connect/handle-verification-updates.md#listen-for-account-updates).

## API-based onboarding 

If you use a custom API-based onboarding flow, you must update it to handle any changed requirements. You can also consider replacing your API-based onboarding flow with [embedded components](https://docs.stripe.com/connect/embedded-onboarding.md) or [Stripe-hosted onboarding](https://docs.stripe.com/connect/hosted-onboarding.md).

### 1. Preview updated verification requirements 

When verification requirements change, you must collect updated information by a certain deadline. Failure to fulfill changed requirements for a connected account can disable one or more of that account’s capabilities. See details about the [information you need to collect](https://docs.stripe.com/connect/required-verification-information.md) based on an account’s region, capabilities requested, and other factors.

You can preview information about upcoming requirements changes by looking at the `Account` object’s [future_requirements](https://docs.stripe.com/api/accounts/object.md#account_object-future_requirements) hash. To avoid disruption of your connected accounts’ capabilities, collect information for future requirements before the `future_requirements.current_deadline`, when they move to the `requirements` hash.

You can also find accounts with outstanding requirements on the [Connected accounts](https://dashboard.stripe.com/connect/accounts-list) page in your Dashboard, where you can filter by account issue and status.

If your connected accounts don’t yet have the updated requirements in `future_requirements`, or you want to test different configurations, you can use the form on the [required verification information page](https://docs.stripe.com/connect/required-verification-information.md). You can also [create test accounts](https://docs.stripe.com/connect/testing.md).

```json
{
  "id": ""{{CONNECTED_ACCOUNT_ID}}"",
  "object": "account","future_requirements": {
    "current_deadline": 1656608400,
    "currently_due": [
      "company.tax_id"
    ],
    "disabled_reason": null,
    "errors": [],
    "eventually_due": [
      "company.tax_id"
    ],
    "past_due": [],
    "pending_verification": []
  },
  ...
}
```

> If you use [Stripe Data](https://docs.stripe.com/stripe-data.md), you can retrieve the `future_requirements` hash using [a Sigma query](https://docs.stripe.com/stripe-data/query-connect-data.md#account-requirements).

#### 2. Add required fields to your onboarding flow 

When you’ve identified the updated information you need to collect, determine whether to add it to your onboarding flow. For example, if the update is a new requirement that always applies to a capability, and your onboarding flow requests that capability, then your flow must collect that information.

Alternatively, if the update changes a requirement because an account reached a threshold, consider how frequently your accounts reach that threshold. If it isn’t common, then your onboarding flow doesn’t need to require every new connected account to provide that information.

To prepare for requirements that apply when an account reaches a threshold, examine the [future_requirements.eventually_due](https://docs.stripe.com/api/accounts/object.md#account_object-future_requirements-eventually_due) array.

Update your onboarding form to collect the new fields, then submit them using the [Accounts](https://docs.stripe.com/api/accounts/update.md) or [Persons](https://docs.stripe.com/api/persons/update.md) API.

### 3. Test your updated onboarding flow 

To simulate future verification requirements, create a test account using the Accounts API and set its [email](https://docs.stripe.com/api/accounts/create.md#create_account-email) parameter to `enforce_future_requirements`. That populates the account’s `requirements` hash with all known future verification requirements.

#### With controller properties

```curl
curl https://api.stripe.com/v1/accounts \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "controller[stripe_dashboard][type]=none" \
  -d "controller[fees][payer]=application" \
  -d "controller[losses][payments]=application" \
  -d "controller[requirement_collection]=application" \
  -d country=US \
  -d business_type=individual \
  -d "capabilities[card_payments][requested]=true" \
  -d "capabilities[transfers][requested]=true" \
  --data-urlencode "email=jenny.rosen+enforce_future_requirements@example.com"
```

#### With account type

```curl
curl https://api.stripe.com/v1/accounts \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d type=custom \
  -d country=US \
  -d business_type=individual \
  -d "capabilities[card_payments][requested]=true" \
  -d "capabilities[transfers][requested]=true" \
  --data-urlencode "email=jenny.rosen+enforce_future_requirements@example.com"
```

To verify that your updated onboarding flow fulfills the account requirements, onboard the test account and check its `requirements` hash. If your flow covers all the requirements, the [currently_due](https://docs.stripe.com/api/accounts/object.md#account_object-requirements-currently_due) array is empty. See the [testing guide](https://docs.stripe.com/connect/testing.md) for additional tools to simulate specific account states.

### 4. Verify submitted future requirements 

After submitting required information, check whether the requirement is still in the `future_requirements` hash. If it isn’t there, then the requirement has been successfully fulfilled.

If the requirement is still present in `future_requirements`, check the `future_requirements.errors` array for an entry with a `requirement` property matching the requirement name. That error can contain information about why the requirement isn’t fulfilled.

If the requirement doesn’t have any matching errors, then examine the `future_requirements.pending_verification` array. If it includes the requirement, then Stripe is still processing the information. Check it again later.

When Stripe receives updated information, we need time to verify that it satisfies the associated requirements. Until verification completes, assume that any related functionality remains disabled. To detect verification updates, listen for [account.updated](https://docs.stripe.com/api/events/types.md#event_types-account.updated) events and inspect them for [verification errors](https://docs.stripe.com/connect/handling-api-verification.md#validation-and-verification-errors). A disabled capability’s `requirements` hash contains a [disabled_reason](https://docs.stripe.com/api/capabilities/object.md#capability_object-requirements-disabled_reason) that you can use to determine the action you must take.

If a submission fails validation, you see errors in `future_requirements.errors`:

```json
{
  "future_requirements": {
    "currently_due": ["company.tax_id"],
    "errors": [
      {
        "code": "invalid_tax_id_format",
        "requirement": "company.tax_id",
        "reason": "Tax IDs must be a unique set of 9 numbers without dashes or other special characters."
      }
    ]
  }
}
```

Make sure your integration parses the `errors` array, displays relevant error messages to your connected accounts, and allows them to correct and resubmit the information. See [the testing guide](https://docs.stripe.com/connect/testing.md) for a full set of testing tools.

## Listen for account updates 

Detect account status changes by listening to the [account.updated](https://docs.stripe.com/api/events/types.md#event_types-account.updated) event. When active or future requirements change, the event includes the updated account object. To monitor future requirements, make sure your webhook handler correctly parses `future_requirements` from the payload:

```json
{
  "type": "account.updated",
  "data": {
    "object": {
      "id": ""{{CONNECTED_ACCOUNT_ID}}"",
      "future_requirements": {
        "currently_due": ["company.tax_id"],
        "past_due": ["company.tax_id"]
      }
    }
  }
}
```

After an account has gone through your onboarding flow, inspect the `currently_due` and `pending_verification` arrays in the account’s `future_requirements` hash. When both are empty, and `future_requirements.disabled_reason` is null, the account is compliant with all applicable future requirements.

## API version considerations 

In [API version 2023-10-16](https://docs.stripe.com/upgrades.md#2023-10-16) and later, the `Account` object’s [requirements.errors](https://docs.stripe.com/api/accounts/object.md#account_object-requirements-errors) array specifies any verification error types in the `code` attribute. If you use an earlier API version, we strongly recommend upgrading to the latest API version and using `requirements.errors`.

If you can’t update to version 2023-10-16, earlier versions of the `requirements.errors` array include a `detailed_code` field to return verification errors that weren’t compatible with the `code` attribute. The `detailed_code` attribute doesn’t appear in the API reference.

If you’re using account or remediation links to collect new requirements, set the [API version to 2021-09-07](https://docs.stripe.com/sdks/set-version.md) or later.

If you’re receiving `account.updated` events. Set the webhooks [API version to 2021-09-07](https://docs.stripe.com/upgrades.md#2021-09-07) or later.

## Readiness checklist 

Use this checklist to make sure your integration is ready for upcoming requirements changes:

- Retrieve accounts and confirm you can read `future_requirements`
- Identify new requirement strings and understand what information to collect
- Update onboarding forms to collect new required fields (API-based onboarding only)
- Submit test data and verify requirements clear from `future_requirements`
- Handle errors by testing invalid submissions and verifying error handling
- Process webhooks for `account.updated` events with `future_requirements` changes
- Test with multiple accounts to ensure consistency across different business types

## See also

- [Handling verification with the API](https://docs.stripe.com/connect/handling-api-verification.md)
- [Required verification information](https://docs.stripe.com/connect/required-verification-information.md)
- [Testing Connect](https://docs.stripe.com/connect/testing.md)
- [Testing account identity verification](https://docs.stripe.com/connect/testing-verification.md)
- [Document verification for connected accounts](https://docs.stripe.com/connect/additional-verifications/identity-document.md)