Handle verification updates

Onboarding flow options

When requirements change, we update Stripe-hosted and embedded onboarding flows to reflect the changes. However, if you use a custom API-based onboarding flow, you must update it to handle any changed requirements.

Regardless of the onboarding flow type, you must address requirements changes for your existing connected accounts.

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": 
"{{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": []
  },
  ...
}

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.

You can also prepare for requirements that will apply when an account reaches their thresholds by considering the future_requirements.eventually_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.

curl https://api.stripe.com/v1/accounts \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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"

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.

curl https://api.stripe.com/v1/accounts/
{{CONNECTED_ACCOUNT_ID}} \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:"

{
  "id": 
"{{CONNECTED_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": []
  },
  ...
}

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 onboarding using Account 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 tab in your Connect 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

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, use the enforcement date as a reminder to check the Accounts to review tab in your Connect Dashboard.

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.

Future requirements can immediately affect an account’s capabilities when they become current requirements. Make sure to address all requirements before their deadlines, even if they’re still in future_requirements.

When your accounts have requirements that are currently_due, direct your accounts to address any issues according to your onboarding flow or with remediation links:

• API-based onboarding: Use your custom onboarding flow, optionally collecting future_requirements as well.
• Embedded onboarding: Render the embedded onboarding component for affected accounts.
• Stripe-hosted onboarding: 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.
• Remediation links: Use the Dashboard to generate remediation links that your connected accounts can use to provide required information.