Stripe-hosted onboarding
Stripe-hosted onboarding handles the collection of business and identity verification information from connected accounts. It’s a web form hosted by Stripe that adjusts dynamically based on the capabilities, country, and business type of each connected account. Stripe-hosted onboarding is the recommended solution for platform’s looking for Stripe to take care of onboarding with little effort from the platform.
The hosted onboarding form in Stripe’s sample integration, Rocket Deliveries.
Customize the onboarding formDashboard
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 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 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.
Create an Account LinkServer-side
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.
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.
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 Stripe-hosted onboarding form.
Handle the connected account returning to your platform
The Account Link requires a refresh_url
and return_url
to handle all cases in which the connected account is redirected back to your platform. It’s important to implement these correctly to provide the best onboarding flow for your connected accounts.
Note
You can use HTTP for your refresh_url
and return_url
while you’re in test mode (for example, to test locally), but for live mode only HTTPS is accepted. Be sure you’ve swapped any testing URLs for HTTPS URLs before going live.
Refresh URL
Your connected account is redirected to the refresh_url
when:
- The link is expired (a few minutes went by since the link was created).
- The link was already visited (the connected account refreshed the page or clicked the back or forward button).
- The link was shared in a third-party application such as a messaging client that attempts to access the URL to preview it. Many clients automatically visit links which causes them to become expired.
The refresh_url
should call a method on your server to create a new Account Link with the same parameters and redirect the connected account to the new Account Link URL.
Return URL
Stripe redirects the connected account back to this URL when they complete the onboarding flow or click Save for later at any point in the flow. It does not mean that all information has been collected, or that there are no outstanding requirements on the account. It only means the flow was entered and exited properly.
No state is passed with this URL. After a connected account is redirected to the return_url
, determine if the account has completed onboarding. Retrieve the account and check the requirements attribute for outstanding requirements. Or, listen to the account.updated
event sent to your webhook endpoint and cache the state of the account in your application. If the account hasn’t completed onboarding, provide prompts in your application to allow them to continue onboarding later.
Handle connected account-initiated updates
Stripe-hosted onboarding also supports connected account-initiated updates to the information they’ve already provided. When you create an Account Link, you can set the type
to either account_onboarding
or account_update
.
Account onboarding
Account Links of this type provide a form for inputting outstanding requirements. Use it when you’re onboarding a new connected account, or when an existing user has new requirements (such as when a connected account had already provided enough information, but you requested a new capability that needs additional info). Send them to this type of Account Link to just collect the new information you need.
Account update
Account Links of this type are enabled for accounts where your platform is responsible for requirement collection. account_update
links display the attributes that are already populated on the account object and allows your connected account to edit previously provided information (for example, they need to update their address). Provide an option in your application (for example, “edit my profile” or “update my verification information”) for connected accounts to make updates themselves.
Supported browsers
Stripe-hosted onboarding supports:
- The last 20 major versions of Chrome and Firefox
- The last two major versions of Safari and Edge
- The last two major versions of mobile Safari on iOS
Stripe-hosted onboarding isn’t supported when embedded through webviews. It’s only supported in standalone browsers.