Embedded onboarding
Provide your connected accounts a localized onboarding form that validates data.
Embedded onboarding is a themeable onboarding UI with limited Stripe branding. You embed the Account onboarding component in your platform application, and your connected accounts interact with the embedded component without leaving your application.
The component supports networked onboarding, which allows owners of multiple Stripe accounts to share business information between them. When they onboard an account, they can reuse that information from an existing account instead of resubmitting it.
Embedded onboarding uses the Accounts API to read the requirements and generate an onboarding form with data validation, localized for all Stripe-supported countries. In addition, embedded onboarding handles all:
- Business types
- Configurations of company representatives
- Verification document uploading
- Identity verification and statuses
- International bank accounts
- Error states
This demo lets you explore the embedded onboarding component’s interface:
Create an account and prefill informationServer-side
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.
If you specify the account’s country or request any capabilities for it, then the account owner can’t change its country. Otherwise, it depends on the account’s Dashboard access:
- Full Stripe Dashboard: During onboarding, the account owner can select any acquiring country, the same as when signing up for a normal Stripe account. Stripe automatically requests a set of capabilities for the account based on the selected country.
- Express Dashboard: During onboarding, the account owner can select from a list of countries that you configure in your platform Dashboard Onboarding options. You can also configure those options to specify the default capabilities to request for accounts in each country.
- No Stripe Dashboard: If Stripe is responsible for collecting requirements, then the onboarding flow lets the account owner select any acquiring country. Otherwise, your custom onboarding flow must set the country and request capabilities.
The response includes the ID, which you use to reference the Account
throughout your integration.
Request capabilities
You can request capabilities when creating an account by setting the desired capabilities’ requested
property to true. For accounts with access to the Express Dashboard, you can also configure your Onboarding options to automatically request certain capabilities when creating an account.
Stripe’s onboarding UIs automatically collect the requirements for requested capabilities. To reduce onboarding effort, request only the capabilities you need.
Prefill information
If you have information about the account holder (like their name, address, or other details), you can simplify onboarding by providing it when you create or update the account. The onboarding interface asks the account holder to confirm the pre-filled information before accepting the Connect service agreement.
If you onboard an account and your platform provides it with a URL, prefill the account’s business_profile.url. If the business 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 up front or incrementally. Up-front onboarding collects the eventually_
requirements for the account, while incremental onboarding only collects the currently_
requirements.
Onboarding type | Advantages |
---|---|
Up-front |
|
Incremental |
|
To determine whether to use up-front or incremental onboarding, review the requirements for your connected accounts’ locations and capabilities. 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_
parameter. To collect the account’s future requirements, set collection_
to include
.
Customize the policies shown to your users
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.
Integrate the account onboarding componentServer-sideClient-side
Create an Account Session by specifying the ID of the connected account and account_
as the component to enable.
Create an Account Session
When creating an Account Session, enable account onboarding by specifying account_
in the components
parameter.
After creating the Account Session and initializing ConnectJS, you can render the Account onboarding component in the front end:
The StepChange object
The StepChange
type is defined in connect.
. Every time the connected account navigates from one step to another in the onboarding process, the step change handler receives a StepChange
object with the following property:
Name | Type | Example value |
step | string (must be a valid step name) | business_ |
The unique reference to an onboarding step. |
Step Restrictions
- The
StepChange
object is only for analytics. - Steps can appear in any order and can repeat.
- The list of valid
step
names can change at any time, without notice.
Step Names
Each page in an onboarding flow has one of the following step names.
Step name | Description |
---|---|
stripe_ | User authentication includes a popup to a Stripe-owned window. The connected account must authenticate before they can continue their workflow. |
risk_ | Guides the connected account to resolve risk-related requirements. |
legal_ | Connected accounts can optionally reuse business information from existing accounts with the same owner. |
business_ | Sets the business type of the connected account. In certain cases the connected account can also set their country. |
business_ | Collects information related to the connected account’s business. |
business_ | Collects a proof of entity document establishing the business’ entity ID number, such as the company’s articles of incorporation. Or allows users to correct wrongly entered information related to the entity. |
business_ | Collects documents needed to verify that bank account information, such as the legal owner’s name and account number, match the information on the user’s Stripe account. |
business_ | Collects other documents and verification requirements related to the business. |
representative_ | Collects information about the account representative. |
representative_ | Collects a government-issued ID verifying the existence of the account representative. |
representative_ | Collects an additional document to verifying the details of the account representative. |
legal_ | Collects the legal guardians consent for accounts opened by minors. |
owners | Collects information about the beneficial owners of a company. |
directors | Collects information about the directors of a company. |
executives | Collects information about the executives of a company. |
proof_ | Collects documentation that verifies a company’s beneficial owners. |
proof_ | Collects documentation to verify that the account representative holds a position of sufficient authority within a company. |
confirm_ | Allows connected accounts to attest that the beneficial owner information provided to Stripe is both current and correct. |
risa_ | (Applies only to businesses in Japan.) Answers questions concerning the Revised Installment Sales Act. |
treasury_ | Collects Treasury and Card Issuing terms of service when requesting those capabilities. |
external_ | Collects the external account of the connected account. |
support_ | Collects information that helps customers recognize the connected accounts business. This support information can be visible in payment statements, invoices, and receipts. |
climate | Allows a connected account to opt into Stripe Climate. |
tax | Allows a connected account to opt into Stripe Tax. |
summary | Final review step of onboarding. The connected account can update entered information from this step. The terms of service and privacy URL is displayed in this screen. |
summary_ | From the summary step, a connected account can update information related to risk requirements. |
summary_ | From the summary step, a connected account can update information related to their business type. |
summary_ | From the summary step, a connected account can update information related to their business. |
summary_ | From the summary step, a connected account can update public-facing information related to their business. |
summary_ | From the summary step, a connected account can update information about each person on their account. |
summary_ | From the summary step, a connected account can update information related to their external account. |
summary_ | From the summary step, a connected account can update information related to their Stripe Tax integration. |
summary_ | From the summary step, a connected account can update information related to their W8/W9 certified tax information. This is shown when Stripe must collect W8/W9 information. |
summary_ | From the summary step, a connected account can update information related to their Stripe Climate integration. |
Identify and address requirement updatesServer-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_
or eventually_
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 the future requirements for your accounts.
For connected accounts where controller.requirement_collection is stripe
, stop receiving updates for identity information after creating an Account Link or Account Session.
Accounts store identity information in the company
and individual
hashes.
Handle verification errors 
Listen to the account.updated event. If the account contains any currently_
fields when the current_
arrives, the corresponding functionality is disabled and those fields are added to past_
.
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_
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.