Stripe-hosted onboarding

Go to the Connect settings page in the Dashboard to customize the visual appearance of the form with your brand’s name, color, and icon. Stripe-hosted onboarding requires this information. Stripe also recommends collecting bank account information from your connected accounts as they’re onboarding.

Create a connected account with the default controller properties. See design an integration to learn more about controller properties. Alternatively, you can create a connected account by specifying an account type.

curl -X POST https://api.stripe.com/v1/accounts \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:"

If you know the country for your connected account, you can provide that information when you create the account. The country defaults to the same country as your platform if not provided.

To request capabilities for your connected account, you can provide that information when you create the account. Stripe’s onboarding UIs automatically collect the requirements for those capabilities. To reduce onboarding effort, request only the capabilities you need. If you omit capabilities, and your connected account has access to the full Stripe Dashboard or the Express Dashboard, capabilities are automatically requested. For accounts with access to the Express dashboard, Stripe-hosted onboarding uses the Configuration settings to request capabilities based on the account’s country.

If you have information about the account holder (like their name, address, or other details), you can proactively provide this when you create or update the account. Stripe-hosted onboarding asks the account holder to confirm the pre-filled information before accepting the Connect service agreement. Providing more information through the API reduces the number of prompts and enhances the onboarding flow for your connected account.

Additionally, if you onboard an account without its own website and your platform provides the account with a URL, prefill the account’s business_profile.url. If the account doesn’t have a URL, you can prefill its business_profile.product_description instead.

When testing your integration, use test data to simulate different outcomes including identity verification, business information verification, payout failures, and more.

As the platform, you must decide if you want to collect the required information from your connected accounts upfront or incrementally. Upfront onboarding collects the eventually_due requirements for the account, while incremental onboarding only collects the currently_due requirements.

To determine whether to use upfront or incremental onboarding, review the required information for the countries where your connected accounts are located to understand the requirements that are eventually due. While Stripe tries to minimize any impact to connected accounts, requirements might change over time.

For connected accounts where you’re responsible for requirement collection, you can customize the behavior of future requirements using the collection_options parameter. Set collection_options.future_requirements to include to collect the account’s future requirements.

Create an Account Link using the connected account ID and include a refresh URL and a 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 collection_options.fields. This example passes eventually_due to use upfront onboarding. Set to currently_due for incremental onboarding.

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

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.

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 mode trigger cards.

Based on your application’s verification requirements, send the connected account back through onboarding when it has currently_due or eventually_due requirements. Use these signals to determine when it’s necessary to re-initiate onboarding for a connected account.

You don’t need to worry about determining which requirements are missing. Onboarding collects the necessary information. For example, if there’s a typo preventing verification, onboarding prompts the connected account to upload an identity document (such as a Driver’s License in the United States). If any information is missing, onboarding requests it.

Stripe notifies you about any upcoming requirements updates that affect your connected accounts. You can proactively collect this information by reviewing the future requirements for your accounts.

Handle verification errors

Listen to the account.updated event. If the account contains any currently_due fields when the current_deadline arrives, the corresponding functionality is disabled and those fields are added to past_due.

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