This document assumes you’re familiar with managed accounts overall, as well as updating accounts and identity verification.

Your platform is responsible for the identity verification process for its managed accounts. Connect streamlines this process by allowing managed accounts to be incrementally verified. Instead of requiring all information up front, Connect asks for a minimal set of information initially but limits how the account can be used (usually by blocking payouts past a certain limit). As the account provides Stripe with more information, we relax these limitations.

This incremental model of verification is split into stages. Once a managed account does a certain volume, a stage is “triggered”, meaning Stripe will ask for that stage’s information requirements. Once triggered, you have to provide the requested information within a limited time and additional charge volume. Once you’ve provided this information, a stage is completed. We allow you to provide information that may be required before a stage is triggered, which can minimize inconveniences.

The diagram above demonstrates the stages involved in incremental verification for U.S. managed accounts. Note that each country has different requirements.

In test mode, transitioning between the different stages is done with special credit card numbers.

Let’s manually go through the verification process for a new managed account. It’s recommended to follow this series of commands sequentially. Please note that multiple steps can be completed at the same time: for example, you can create an account with a name and date of birth, bank account, and terms of service acceptance info. This would immediately bypass the first stage of verification, and jump you right to step 5 in this flow.

1. Creating a managed account

Let’s start by creating a new test mode managed account, adding a bank account, and showing that the managed account holder has accepted the Stripe Terms of Service (ToS.) Explicit ToS acceptance is required for making transfers.

2. First verification stage

Initially, no stages are active. At this point you can make charges but not transfer funds. That is the starting state of all managed accounts.

Now you will trigger the account’s first stage with one of our test card numbers (4000 0000 0000 4202). This magic credit card simulates crossing the stage’s trigger threshold. Typically this happens after crossing a specific dollar amount in total charges.

You should now see that in addition to requesting additional information via verification[fields_needed], there’s now a deadline for providing this information in the verification[due_by] field.

This is because you have triggered the first stage. In this stage, just as with the initial state, charges are enabled but transfers are disabled. You’ll see that charges_enabled on your account is still true: Stripe has given you a deadline to provide this information, but you have not passed it yet.

3. Triggering charge limits

While the stage allows charges at first, it has a limit to the volume of charges you can make while in that stage. To simulate crossing that limit, you will make a charge with another trigger card number (4000 0000 0000 4210).

Now you are not able to make new charges, and the account has been updated to show both charges_enabled as false and verification[disabled_reason] as fields_needed.

4. Fulfilling the first stage

To know what fields you need to provide at this stage, you should first get a list of necessary fields.

You’ll see that in the U.S. these verification[fields_needed] are first_name, last_name, and dob.

Stripe must collect this initial set of fields in order to satisfy our OFAC requirements. Because of the nature of these checks, if they are not provided Stripe must block charges for the account. While you can charge a certain amount before collecting name and date of birth, since charge blocking is so disruptive to a business, we highly recommend collecting these fields upfront to avoid any potential issues.

Once you provide this information, Stripe immediately re-enables charges, and enables transfers. You’ll also notice that while verification[fields_needed] is still set (with different values,) verification[due_by] is not. This means that while Stripe will require more information in the future, it’s not immediately required, and you are able to defer providing it until the account has charged more.

5. Second stage

Let’s go ahead and trigger the next stage using the trigger threshold magic card.

You can still charge and transfer, just as before, but now verification[due_by] on the account is set, meaning you need to provide more information in the near future.

The worst that can happen in this stage is that Stripe will disable transfers (again, the only time Stripe disables charges due to verification is in the first stage).

6. Triggering transfer limits

While this stage does not have a charge-disabling limit, it does have a transfer-disabling limit. You can trigger a transfer limit using a trigger card number (4000 0000 0000 4236). This is similar to the charge limit, but it blocks transfers.

After this trigger, all transfers should fail.

7. Fulfilling the second stage

After fulfilling the stage, transfers work again.

8. Fulfilling multiple stages

As noted before, providing the right information can fulfill multiple stages. Let’s try to complete the last two stages all at once.

First, obtain the test success image by running wget https://stripe.com/img/documentation/guides/testing/success.png.

From here, you can upload the test success image.

Once the image is uploaded, you can update the account with both pieces of verification information.

This single update will actually jump through two stages, from stage 2 fulfilled to complete. You can confirm verification with a GET account call.

You’ll see that verification[fields_needed] is now empty, meaning Stripe will not need any additional information for this account unless a significant exception happens (for example, if the account appears to be used for fraud).