Onboard your connected account

Choose between Stripe-hosted or embedded onboarding to collect requirements from your connected accounts.

After you create a connected account on your platform, you must provide a way for the account to complete onboarding requirements. You can use Stripe-hosted onboarding (redirect to Stripe) or Embedded onboarding (stay in your app).

Note

Stripe-hosted onboarding is only supported in web browsers. You can’t use it in embedded web views inside mobile or desktop applications.

Determine the information to collect

As the platform, you must decide if you want to collect the required information from your connected accounts up front or incrementally. Up-front onboarding collects the eventually_due requirements for the account, while incremental onboarding only collects the currently_due requirements. You can control this behaviour using the collection_options.fields parameter.

To determine whether to use up-front or incremental onboarding, review the requirements for your connected accounts’ locations and capabilities. While Stripe tries to minimise any impact to connected accounts, requirements might change over time.

For connected accounts where you’re responsible for requirement collection, you can customise the behaviour of future requirements using the collection_options parameter. To collect the account’s future requirements, set collection_options.future_requirements to include.

Collect additional public details

Stripe collects the required public details for each connected account. You can choose additional fields to collect during onboarding according to your business needs. Any fields you choose that Stripe doesn’t require appear as optional, and connected accounts can choose whether to provide them.

1. In the Public details settings in the Dashboard, enable the Collect public details toggle.
2. Select the fields to show to connected accounts during onboarding.
3. Click Save .

Available fields

You can collect the following public details:

Requirements vary

Stripe’s requirements vary by connected account based on their business type, country, and requested capabilities. Enable fields to make sure they always appear during onboarding, whether or not they’re required.

Create an Account Link Server-side

Create an Account Link using the connected account ID and include a use_case.account_onboarding.refresh_url and a use_case.account_onboarding.return_url. Stripe redirects the connected account to the refresh URL if the Account Link URL has already been visited, has expired, or is otherwise invalid. Stripe redirects connected accounts to the return URL when they have completed or left the onboarding flow. Additionally, based on the information you need to collect, pass either currently_due or eventually_due for use_case.account_onboarding.collection_options.fields. This example passes eventually_due to use up-front onboarding. For incremental onboarding, set it to currently_due.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

Redirect your connected account to the Account Link URL

Redirect the connected account to the Account Link URL to send them to the onboarding flow. Each Account Link URL can only be used once, because it grants access to the account holder’s personal information. Authenticate the account in your application before redirecting them to this URL.

Identify and address requirement updates Server-side

Set up your integration to listen for changes to account requirements. You can test handling new requirements (and how they might disable charges and payouts) with the test trigger cards.

Send a connected account back through onboarding when it has any currently_due or eventually_due requirements. You don’t need to identify the specific requirements, because the onboarding interface knows what information it needs to collect. For example, if a typo is preventing verification of the account owner’s identity, onboarding prompts them to upload an identity document.

Stripe notifies you about any upcoming requirements updates that affect your connected accounts. You can proactively collect this information by reviewing your accounts’ requirements that have a requested_reasons.code of future_requirements.

For connected accounts where Stripe is responsible for collecting requirements, stop receiving updates for identity information after creating an Account Link or Account Session.

Accounts store identity information in the identity hash.

Account v2 webhook event change

For Account v2, create an event destination to listen for v2.core.account[requirements].updated events instead of the account.updated v1 event.

Handle verification errors

Listen to the v2.core.account[requirements].updated event. If the account contains any requirements with a minimum_deadline.status of currently_due when the deadline arrives, the corresponding functionality is disabled and those statuses become past_due.

Let your accounts remediate their verification requirements by directing them to the Stripe-hosted onboarding form.

Handle the connected account returning to your platform Server-side

The Account Link requires a refresh_url and return_url to handle all cases in which the connected account is redirected back to your platform. It’s important to implement these correctly to provide the best onboarding flow for your connected accounts.

Note

You can use HTTP for your refresh_url and return_url while you’re in a testing environment (for example, to test locally), but live mode only accepts HTTPS. You must update any testing URLs to HTTPS URLs before you go live.

Refresh URL

Your connected account is redirected to the refresh_url when:

• The link expired (a few minutes went by since the link was created).
• The link was already visited (the connected account refreshed the page or clicked the back or 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 causes an Account Link to expire.

Configure the refresh_url to call a method on your server to create a new Account Link with the same parameters and redirect the connected account to the new Account Link URL.

Return URL

Stripe redirects the connected account back to this URL when they complete the onboarding flow or click Save for later at any point in the flow. It doesn’t 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.

This URL passes no state. After redirecting a connected account to the return_url, determine whether the account completed onboarding. Retrieve the account and check the requirements hash for outstanding requirements. Alternatively, listen to the v2.core.account[requirements].updated event sent to your webhook endpoint and cache the state of the account in your application. If onboarding is incomplete, provide prompts in your application to allow them to continue onboarding later.

Handle connected account-initiated updates Server-side

Stripe-hosted onboarding also supports connected account-initiated updates to the information they’ve already provided. Listen to the v2.core.account[requirements].updated event sent to your webhook endpoint to be notified when the account completes requirements and updates their information.

When you create an Account Link, you can set the type to either account_onboarding or account_update.

Account Link type restriction

You can create Account Links of type account_update only for connected accounts where your platform is responsible for collecting requirements, including Custom accounts. You can’t create them for accounts that have access to a Stripe-hosted Dashboard. If you use Connect embedded components, you can include components that allow your connected accounts to update their own information. For an account without Stripe-hosted Dashboard access where Stripe is liable for negative balances, you must use embedded components.

Account Links for account_onboarding

Account Links of this type provide a form for inputting outstanding requirements. Use it when you’re onboarding a new connected account or when an existing user has new requirements (such as when a connected account had already provided enough information, but you requested a new capability that needs additional information). Send them to this type of Account Link to just collect the new information you need.

Account Links for account_update

Account Links of this type are enabled for accounts where your platform is responsible for requirement collection. account_update links display the attributes that are already populated on the account object and allow the connected account to edit previously provided information. Provide an option in your application (for example, “edit my profile” or “update my verification information”) for connected accounts to make updates themselves.

Next steps

When your connected account is active, build a payments integration so they can begin accepting payments.