Embedded onboarding
Embedded onboarding is a highly themeable onboarding UI with limited Stripe branding. Your platform embeds the Account onboarding component in your application, and your connected accounts interact with the embedded component without ever leaving your application. Embedded onboarding uses the Accounts API to read the requirements and generate an onboarding form with robust data validation and is localized for all Stripe-supported countries. In addition, embedded onboarding handles all:
- Business types
- Configurations of company representatives
- Verification document uploading
- Identify verification and statuses
- International bank accounts
- Error states
Create an account and prefill informationServer-side
Create a connected account by specifying the account type.
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.
If you need to request capabilities for your connected account, you can provide that information when you create the account and Stripe’s onboarding UIs 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 Express Dashboard access, Stripe-hosted onboarding uses the Configuration settings to automatically 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.
Determine the information to collect
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.
Upfront onboarding | Incremental onboarding | |
---|---|---|
Advantages |
|
|
Disadvantages |
|
|
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 collectionOptions
attribute when integrating the Account onboarding component.
Customize the policies shown to your users
Stripe’s service agreement and Privacy Policy are shown to connected accounts in embedded onboarding. Connected account users who haven’t accepted Stripe’s services agreement are asked to accept it on the final screen of onboarding. 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, outlined below.
Handle service agreement acceptance on your own
If you’re a platform onboarding connected accounts where you are responsible for requirement collection, you can collect Terms of Service acceptance using your own process instead of in the embedded account onboarding component. In that case, 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 choose to 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 your connected accounts where you are responsible for requirement collection, you can replace those links with your own agreements and policy. Follow these instructions to incorporate the Stripe services agreement and link to the Stripe Privacy Policy.
Integrate the account onboarding componentServer-sideClient-side
Create an Account Session by specifying the ID of the connected account and account_onboarding
as the component to enable.
Creating an Account Session
When creating an Account Session, enable account management by specifying account_onboarding
in the components
parameter.
After creating the Account Session and initializing ConnectJS, you can render the Account onboarding component in the front end:
Handle new requirements becoming dueServer-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 mode trigger cards. Stripe notifies you when upcoming requirements updates affect your connected accounts.
You can proactively collect information to fulfill future requirements. Based on the verification needs of your application, send the connected account back into onboarding as necessary to satisfy currently_due
or eventually_due
requirements. You can use this as a signal of when to send your connected account back into the flow.
You don’t need to worry about what the requirements are—sending the connected account back into onboarding collects the right information. For example, if your connected account 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 onboarding prompts them to upload such a document to make sure they’re verified.
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.