Embedded 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.

For connected accounts where you’re responsible for requirement collection, you can customize the behavior of future requirements using the collectionOptions attribute when integrating the Account onboarding component. Set collectionOptions.futureRequirements to include which collects the account’s future requirements.

Connected accounts see Stripe’s service agreement and Privacy Policy during embedded onboarding. Connected account users who haven’t accepted Stripe’s services agreement must accept it on the final onboarding screen. Embedded onboarding also has a footer with links to Stripe’s service agreement and Privacy Policy.

For connected accounts where the platform is responsible for requirement collection, you have additional options to customize the onboarding flow, as outlined below.

Handle service agreement acceptance on your own

If you’re a platform onboarding connected accounts where you’re responsible for requirement collection, you can collect Terms of Service acceptance using your own process instead of using the embedded account onboarding component. If using your own process, the final onboarding screen only asks your connected accounts to confirm the information they entered, and you must secure their acceptance of Stripe’s service agreement.

Embedded onboarding still has links to the terms of service (for example, in the footer) that you can replace by linking to your own agreements and privacy policy.

Link to your agreements and privacy policy

Connected accounts see the Stripe service agreement and Privacy Policy throughout embedded onboarding. For the connected accounts where you’re responsible for requirement collection, you can replace the links with your own agreements and policy. Follow the instructions to incorporate the Stripe services agreement and link to the Stripe Privacy Policy.

Create an Account Session by specifying the ID of the connected account and account_onboarding as the component to enable.

Create an Account Session

When creating an Account Session, enable account onboarding by specifying account_onboarding in the components parameter.

curl https://api.stripe.com/v1/account_sessions \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d account=
{{CONNECTED_ACCOUNT_ID}} \
  -d "components[account_onboarding][enabled]"=true \
  -d "components[account_onboarding][features][external_account_collection]"=true

After creating the Account Session and initializing ConnectJS, you can render the Account onboarding component in the front end:

// Include this element in your HTML
const accountOnboarding = stripeConnectInstance.create('account-onboarding');
accountOnboarding.setOnExit(() => {
  console.log('User exited the onboarding flow');
});
container.appendChild(accountOnboarding);

// Optional: make sure to follow our policy instructions above
// accountOnboarding.setFullTermsOfServiceUrl('{{URL}}')
// accountOnboarding.setRecipientTermsOfServiceUrl('{{URL}}')
// accountOnboarding.setPrivacyPolicyUrl('{{URL}}')
// accountOnboarding.setSkipTermsOfServiceCollection(false)
// accountOnboarding.setCollectionOptions({
//   fields: 'eventually_due',
//   futureRequirements: 'include',
// })
// accountOnboarding.setOnStepChange((stepChange) => {
//   console.log(`User entered: ${stepChange.step}`);
// });

The stepchange object

Every time the connected account navigates from one step to another in the onboarding process, a stepchange object is passed to the step change handler with the following properties.

Restrictions

• The stepchange object is only for analytics.
• Steps can appear in any order and can be repeated.
• Possible step values can change at any time.

Step Values

Each page in onboarding has a unique step name. This step is an exhaustive list of pages the user could see in the onboarding process. These values can change at any time without notice.

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 Account onboarding component.

Disable Stripe user authentication

When using embedded onboarding, Stripe user authentication is enabled by default. You can use disable_stripe_user_authentication to remove this behavior.

We recommend implementing two-factor authentication or equivalent security measures as a best practice. For account configurations that support this feature, such as Custom, you assume liability for connected accounts if they can’t pay back negative balances.