Migrate your onboarding and requirement update flows to Stripe-hosted or embedded onboarding

To maintain an API-based onboarding flow for your connected accounts, you must update your integration whenever requirements change or when you want to onboard accounts in a new country. Stripe recommends that you avoid those efforts by migrating your flow to use Stripe-hosted or embedded onboarding. Both types can automatically determine which requirements to collect, and both are localized for all countries that Stripe supports.

• Stripe-hosted onboarding: This method requires the least amount of engineering effort. However, it allows very little customization and can’t prevent an account user from changing information that you prefill.
• Embedded onboarding: This method requires more engineering effort, but allows you to build a more customized onboarding interface. You can prevent account users from changing information that you prefill.
• Combined onboarding types: This method requires varying levels of engineering effort, depending on your integration. For example, your API-based flow collects certain requirements, embedded components handle all other requirements, and you provide a Stripe-hosted form for account users to voluntarily update account information.

For more details about the differences between onboarding types, see Choose your onboarding configuration.

Stripe-hosted onboarding

To use Stripe-hosted onboarding, you provide each connected account a single-use, account-specific Account Link that opens a form for collecting information. You can generate an Account Link to collect only outstanding requirements, or to allow an account user to update any accessible account information.

Migrating your connected account onboarding flow to use Stripe-hosted onboarding involves these steps:

1. In your platform Dashboard, open your Connect Onboarding interface settings and click Customize to define the branding of your onboarding form.
2. Select the Onboarding experience tab, then enter your business name and select an icon, logo, and colors. Alternatively, you can select Copy platform branding to apply your platform brand settings to the form.
3. Where your application sends connected account users to your custom onboarding flow, update it to instead generate an Account Link and send them there. When you generate an Account Link, you can configure options such as the following:
   • The URL to direct the account user to when they complete the onboarding flow
   • The URL to direct the account user to if the Account Link is expired or invalid
   • Whether to collect eventually due requirements
   • Whether to collect future requirements
4. Replace both the initial onboarding flow and any flow that collects updated requirements.
5. Deprecate the API-based flows that you no longer need.

Each time an account user accesses Stripe-hosted onboarding, it reflects up-to-date requirements. You don’t have to update your Account Links when requirements change.

For detailed instructions, including how to configure Account Links, see the Stripe-hosted onboarding documentation.

Embedded onboarding

Embedded onboarding requires more engineering effort than Stripe-hosted onboarding, but allows for significantly more customization, such as the following:

• Fully control the design of the pages where you embed components
• Collect only a specified list of requirements
• Exclude a specified list of requirements from collection
• Automatically notify connected accounts of outstanding requirements

You can use the following Connect embedded components to onboard connected accounts and collect requirements:

• Account onboarding: Allows an account user to provide only outstanding requirements. It always includes currently due requirements, and you can configure it to also include eventually due or future requirements.
• Account management: Allows an account user to update various types of account information, including, but not limited to, outstanding requirements. However, a connected account can’t use this component to respond to risk verifications.
• Notification banner: Allows an account user to provide only outstanding requirements. The connected account must have already completed initial onboarding, so you can only use this component for updated requirements or risk verifications. It only renders if the connected account has outstanding requirements, and you can’t configure it to include or exclude specific requirements.

For initial onboarding of connected accounts, use the Account onboarding component.

Full migration with simple collection

Migrating your entire onboarding flow to use embedded onboarding, without restricting account users’ ability to change prefilled information, involves these steps:

1. Design the page that will contain the embedded component. You can use a page from your existing onboarding flow as a starting point.
2. Customize the appearance of the embedded component.
3. Where your application sends connected account users to your custom flow for initial onboarding, update it to instead create an Account Session and mount the account onboarding component. When you create an Account Session, you can configure options such as the following:
   • Whether to collect eventually due requirements
   • Whether to collect future requirements
   • Whether to link to custom terms of service or a custom privacy policy.
   • Whether to collect external account information.
4. Replace each flow in your application that collects updated requirements with one of the relevant embedded components. Using the account management or notification banner component is similar to using the account onboarding component.
5. Deprecate the API-based flows that you no longer need.

Each time a component renders, it reflects up-to-date requirements. You don’t have to update components when requirements change.

For detailed instructions, including how to configure Account Sessions, see the embedded onboarding documentation.

Partial migration or migration with customized collection

You can partially migrate your onboarding and remediation flows or implement customized requirement collection by configuring the account onboarding and account management components to collect only certain information. For example:

• Collect only a specified list of requirements: Use embedded components with the only collection option to collect only certain complex or detailed requirements, and your existing API onboarding flow to collect all other requirements. For example, if you start onboarding accounts in a region with unique proof-of-liveness documentation requirements, you can add an embedded component to collect only those requirements.
• Collect all requirements except a specified list: Prefill certain information when you create an account, and use embedded components with the exclude collection option to prevent account users from changing that information.
• Defer external account collection: Defer collection of external accounts until after a connected account’s first transaction by disabling external account collection during initial onboarding. After an account’s first transaction, present the account onboarding component with external account collection enabled and using the only collection option to collect only the external account.

Migrating your onboarding flow to use embedded onboarding with customized requirement collection involves these steps:

1. Design the page that will contain the embedded component. You can use your existing onboarding page as a starting point.
2. Customize the appearance of the embedded component.
3. Where your application sends connected account users to your custom flow for initial onboarding, update it to instead create an Account Session and mount the account onboarding component. When you create an Account Session, you can configure options such as the following:
   • Whether to collect only a specified list of requirements
   • Whether to exclude a specified list of components from collection, regardless of their status
   • Whether to collect eventually due requirements
   • Whether to collect future requirements
   • Whether to link to custom terms of service or a custom privacy policy
   • Whether to collect external account information
4. Replace each flow in your application that collects updated requirements with one of the relevant embedded components. Using the account management or notification banner component is similar to using the account onboarding component, although you can’t control which requirements the notification banner collects. When requirements change, you don’t have to specify the updated information to collect. You only have to present one of the components to your connected accounts.
5. Deprecate the API-based flows that you no longer need.

Each time a component renders, it reflects up-to-date requirements. You don’t have to update components when requirements change.

For detailed instructions, including how to configure Account Sessions and restrict requirement collection, see the embedded onboarding documentation.

Combined onboarding types

To implement a combination of onboarding types, follow the instructions in Stripe-hosted onboarding and partial embedded onboarding for the requirements that you want to handle with each of those onboarding types. Then, update your API-based flow to handle only the requirements that you don’t migrate. Remember that you can only configure Stripe-hosted onboarding to allow editing of all requirements or outstanding requirements only. For any other configurations, you need to use embedded or API-based onboarding.