Stripe hosted onboarding for Custom accounts

Connect Onboarding for Custom Accounts supports upfront or incremental onboarding. Upfront onboarding collects the eventually_due requirements for the account, while incremental onboarding collects the currently_due requirements. For the advantages and disadvantages of each, see the onboarding flows documentation.

The currently_due requirements request only the user information needed for verification at this specific point in time; the eventually_due requirements include a more complete set of questions that we’ll eventually need to collect.

Based on the needs of your platform, pass either currently_due or eventually_due as the value of the collection_options.fields parameter in your calls to Account Links. Here’s an example request:

curl https://api.stripe.com/v1/account_links \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d account=
{{CONNECTED_ACCOUNT_ID}} \
  --data-urlencode refresh_url="https://example.com/reauth" \
  --data-urlencode return_url="https://example.com/return" \
  -d type=account_onboarding \
  -d "collection_options[fields]"=eventually_due

The response to your Account Links request includes a value for the key url. Redirect your user to this link to send them into the flow. You can only use your Account Link URLs one time because they grant access to the account holder’s personal information. Authenticate the user in your application before redirecting them to this URL. If you enable Collect external account information for Custom accounts in your payout onboarding settings, or if the treasury capability is requested, the user must set up additional authentication with Stripe before entering the onboarding flow.

Connect Onboarding requires you to pass both a return_url and refresh_url to handle all cases in which the user will be redirected back to your platform. It’s important that you implement these correctly to provide the best experience for your user.

return_url

Stripe will issue a redirect back to this URL when the user completes the Connect Onboarding flow, or clicks Save for later at any point in the flow. It does not mean that all information has been collected, or that there are no outstanding requirements on the account. It only means the flow was entered and exited properly.

No state is passed with this URL. After a user is redirected to your return_url, check the state of the requirements attribute on their account. You can either listen to account.updated webhooks or retrieve the Account object and inspect the state of its requirements attribute. See more details in Step 4 below.

refresh_url

Your user will be redirected to the refresh_url in these cases:

• The link is expired (a few minutes went by since the link was created)
• The link was already visited (the user refreshed the page or clicked the back/forward button)
• The link was shared in a third-party application such as a messaging client that attempts to access the URL to preview it. Many clients automatically visit links which cause them to expire.

Your refresh_url should trigger a method on your server to call Account Links again, with the same parameters, and redirect the user back into the Connect Onboarding flow to create a seamless experience.

Set up your integration to listen for changes to account requirements, if you haven’t already done so. We recommend using webhooks to do so. You can test handling new requirements (and how they may disable charges and payouts) with our test mode trigger cards.

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

If you use embedded or Stripe-hosted onboarding, you can proactively collect information to fulfil future requirements. For embedded onboarding, include the collectionOptions attribute in the embedded onboarding component. For Stripe-hosted onboarding, specify the collection_options parameter when creating account links.

Based on the verification needs of your application, send the user back into Connect Onboarding as necessary to satisfy currently_due or eventually_due requirements as described in step 1. You can use this as a signal of when to send your user back into the flow. Keep in mind that using Connect Onboarding means you don’t really need to worry about what the requirements are – sending the user back into Connect Onboarding means it will collect the right information.

For example, if your user mistypes their information and they can’t be verified, they could be asked to provide an Identity Document (for example, a Driver’s License in the United States). Sending this user into Connect Onboarding prompts them to upload such a document to ensure they become verified.

Most Connect Onboarding usage discussed thus far has been about prompting the user to provide new information. Connect Onboarding also supports user-initiated updates to the information they’ve already provided in the type parameter of the Account Link. type accepts one of two values: account_onboarding or account_update.

account_onboarding

This value for type provides a form for inputting outstanding requirements. Use it when you’re onboarding a new user, or when an existing user has new requirements; such as when a user had already provided enough information, but you requested a new capability that needs additional info. Send the user to the form in this mode to just collect the new information you need.

account_update

This value for type displays the attributes that are already populated on the account object and allows your user to edit previously provided information. Provide an access point in your platform website to a type=account_update Account Link for users to make updates themselves (for example, when their address changes). Consider framing the link as “edit my profile” or “update my verification information.”