Handle verification updates
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 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. Such updates can require that you take the following actions:
- Modify your onboarding flow to account for the changed requirements
- Collect updated information from affected connected accounts and handle verification responses
When upcoming requirements updates affect your connected accounts, we’ll notify you.
Note
In API version 2023-10-16 and later, the account object’s requirements.errors array specifies the latest verification error types in the code field. We recommend upgrading to API version 2023-10-16 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 hold verification errors that weren’t compatible with the code field. The detailed_code field doesn’t appear in the API reference.
Modify your onboarding flow
Onboarding flow options
You can onboard your Custom connected accounts in a few different ways.
| Onboarding Flow | Description | Required Action |
|---|---|---|
| API-based | You build custom flows using Stripe APIs for your connected accounts. Your integration must meet all of Stripe’s onboarding requirements. | You’re responsible for identifying requirements changes and updating your flows to handle them. |
| Embedded new | (Recommended method) Your connected accounts interact with a highly themeable and customizable UI in an embedded component without leaving your application. | No action required. Stripe automatically updates embedded onboarding components to handle requirements changes. |
| Stripe-hosted | Your application redirects your connected accounts to Stripe to complete the onboarding process in a co-branded interface. | No action required. Stripe automatically updates hosted onboarding to handle requirements changes. |
If you use embedded components or Stripe-hosted onboarding, requirements changes don’t require you to update your onboarding flow. Skip to the section on collecting updated information.
If you use a custom API-based onboarding flow, handle updated requirements by following these steps or by replacing your onboarding flow with embedded components or Stripe-hosted onboarding.
Modify your API-based onboarding flow
1. Preview updated verification requirements
When verification requirements change, you must collect updated information by a certain date. Otherwise, connected accounts won’t be able to use the capabilities you request (for example, card_payments). See details about the information you need to collect based on an account’s region, capabilities requested, and other factors.
You can avoid disruption of your connected accounts’ capabilities by planning the collection of updated information before the current_deadline. To preview information about upcoming requirements changes, look at the Account object’s future_requirements hash.
{ "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": [] }, ... }"{{CONNECTED_ACCOUNT_ID}}"
Note
If you use Stripe Data, you can retrieve the future_requirements hash using a Sigma query.
2. Add required fields to your onboarding flow
When you’ve identified the updated information you need to collect, add corresponding fields to your onboarding flow and update your connected accounts using the Accounts API.
To avoid disruption to your connected accounts, have your onboarding flow address all requirements listed in the Account object’s future_requirements.currently_due list.
3. Test your updated onboarding flow
To simulate future verification requirements, create a test account using the Accounts API with enforce_future_requirements in the email field. That populates the account’s requirements hash with all known future verification requirements.
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 list is empty.
4. Listen for account status changes to enable functionality
Detect account status changes by listening to the account.updated event. After an account has gone through your onboarding flow, inspect the currently_due and pending_verification lists in the account’s requirements hash. When both are empty, and requirements.disabled_reason is null, you can enable functionality for the account. When payouts_enabled is true, the account can receive payouts. When charges_enabled is true, unlock payments for the account.
{ "id":, "object": "account", "charges_enabled": true, "payouts_enabled": true, "requirements": { "alternatives": [], "current_deadline": null, "currently_due": [], "disabled_reason": null, "errors": [], "eventually_due": [], "past_due": [], "pending_verification": [] }, ... }"{{CONNECTED_ACCOUNT_ID}}"
Collect updated information from accounts with outstanding requirements
You can collect updated information from your connected accounts using embedded components, Stripe-hosted onboarding, or the Stripe API. We recommend either integrating embedded components or directing your connected accounts to Stripe-hosted links.
In all cases, follow these steps:
1. Adjust your integration to handle new verification responses
When Stripe receives updated information about your connected accounts, it takes time to verify the associated account fields. Until we complete verification, assume that any related functionality remains disabled. To detect field verification updates, listen for account.updated events and inspect them for verification errors. If you don’t resolve an error before its deadline, it disables requested capabilities for affected accounts.
A disabled capability’s requirements hash contains a disabled_reason that you can use to determine the action you must take. To investigate or to provide required information, use the Accounts to review page in the Dashboard.
2. Identify accounts with outstanding requirements
In your Connect Dashboard, select Accounts to review. It displays a list of connected accounts with current or future outstanding requirements. You can filter the list by account issue and status.
You can also see what information each connected account must provide, and the deadline, in the account object’s future_requirements hash or by using a Sigma query.
3. Prepare for enforcement of updated requirements
At this point, your onboarding flow collects updated information according to each account’s future_requirements and your integration handles the verification responses. On the enforcement date for an account (future_requirements.current_deadline), the contents of the future_requirements hash move to the requirements hash and Stripe generates an account.updated event. Because this enforcement can cause more accounts to require review, the enforcement date is a good time to check your Accounts to review in the Dashboard.
Note
We plan to introduce a feature that lets you start enforcing requirements before the deadline by applying updated verification requirements to connected accounts. It will let you proactively catch and resolve issues in your updated integration by applying requirements to connected accounts in batches.
4. Send connected accounts to the information collection flow
If any account has currently_due requirements or verification errors, you must address them by the requirements current_deadline. At that deadline, the requirements in the requirements.currently_due array are added to the requirements.past_due array and any associated capabilities become disabled until you provide the information and resolve the errors.
When your accounts have requirements that are currently_due, direct your accounts to address any issues according to your onboarding flow:
- API-based onboarding: Use your custom onboarding flow, optionally collecting
future_requirementsas well. - Embedded onboarding: Render the embedded onboarding component for affected accounts.
- Stripe-hosted onboarding: Send your accounts to your hosted onboarding flow. You can generate links to it in a few ways:
- Use the Account Links API to generate a single-use link to Stripe-hosted onboarding. Send your connected accounts to this link from your application.