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.

These updates might require you to take the following actions:

1. Modify your onboarding flow to account for the changed requirements.
2. Collect updated information from affected connected accounts and handle verification responses.
3. Handle risk-related requirements by notifying connected accounts of identified issues so you can guide them to resolve through Stripe interfaces.

When upcoming requirements updates affect your connected accounts, we’ll notify you.

Identify upcoming requirements

When Stripe is responsible for collecting requirements (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 and Capability 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 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.

If you use Stripe-hosted or embedded onboarding, you can instead collect required information by creating and sharing remediation links.

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.

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 or Stripe-hosted onboarding.

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 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 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 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. You can also create test accounts.

{
  "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, 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 array.

Update your onboarding form to collect the new fields, then submit them using the Accounts or Persons API.

3. Test your updated onboarding flow

To simulate future verification requirements, create a test account using the Accounts API and set its email parameter to enforce_future_requirements. That populates the account’s requirements hash with all known future verification requirements.

curl https://api.stripe.com/v1/accounts \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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 array is empty. See the testing guide 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 events and inspect them for verification errors. A disabled capability’s requirements hash contains a 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:

{
  "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 for a full set of testing tools.

Listen for account updates

Detect account status changes by listening to the 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:

{
  "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 and later, the Account object’s 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 or later.

If you’re receiving account.updated events. Set the webhooks API version to 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