Hosted Onboarding is a web form hosted by Stripe that takes care of collecting identity verification information from users. It dynamically adjusts the information that it collects to reflect the connected account’s capabilities, country, and business type. Hosted Onboarding is the recommended solution to collect identity verification information, and ensures that your flow is optimized for:
- Mobile browsers
- Internationalization and localization
- Conversion rate
- Intelligently requesting requirements based on what’s already provided on the account
Here’s what the form looks like for Stripe’s sample integration, Rocket Deliveries:
How to use Hosted Onboarding
- Go to your Connect settings page to customize the visual appearance of the form: you can provide the name, color, and icon of your brand. More customization options are coming soon.
- Create a new account and get the account ID, or use an existing account ID (in the form of
- Call the Account Links with the following parameters (see the API ref for more):
In the onboarding flow for your own platform, redirect your user to the
urlreturned by Account Links.
- Handle additional account states, redirecting your user back into the Hosted Onboarding flow if necessary. To handle user-initated updates to information they’ve already provided, create a way for your user to get a new redirect to the Hosted Onboarding form from your platform’s dashboard.
Step 1: Determine what information you’d like to collect
Hosted Onboarding supports both upfront or incremental onboarding, the tradeoffs are detailed here. For Hosted Onboarding purposes, “upfront” onboarding means collecting the
eventually_due requirements on the account, and “incremental” onboarding means collecting the
currently_due requirements request only the user information needed for verification at this specific point in time; the
eventually_due requirements include a more complete set of questions that we’ll eventually need to collect.
Your platform should think about tradeoffs for conversion: a simpler upfront experience with
currently_due may require eventually redirecting the user back through this flow to collect additionally required information over time. Conversely, a more complete experience with
eventualy_due may reduce initial conversion because it might collect more information than is strictly necessary to enable charges and payouts on the account.
Based on the needs of your platform, pass either
eventually_due as the value of the
collect parameter in your calls to Account Links.
Step 2: Redirect your user to the Account Link URL
Account Links returns an object with the key
url. Redirect your user to this link to send them into the flow. Account Link URLs are short-lived and can only be used once because they grant access to the account holder’s personal information. Be sure to authenticate the user in your application before redirecting them to this URL.
Step 3: Handle the user returning to your platform
Hosted Onboarding requires you to pass both a
failure_url to handle all cases in which the user will be redirected back to your platform. It’s important that you implement these correctly to provide the best experience for your user.
Stripe will issue a redirect back to this URL when the user completes the Hosted Onboarding flow, or clicks 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 via this URL. After a user is redirected to your
success_url, check the state of the
requirements hash on their account, either by listening to
account.updated webhooks, or calling the Accounts and inspecting the state of the
requirements hash. See more details in Step 4 below.
Your user will be redirected to the
failure_url in these cases:
- The link is expired (a few minutes went by since the link was created)
- The link was already visited (the user refreshed the page or clicked the back/forward button)
- Your platform is no longer able to access the account
- The account has been rejected
failure_url should trigger a method on your server to call Account Links again, with the same parameters, and redirect the user back into the Hosted Onboarding flow to create a seamless experience.
Step 4: Handle the case of new requirements becoming due
Set up your integration to listen for changes to account requirements, if you haven’t already done so. We recommend using webhooks to do so.
Based on the verification needs of your application, send the user back into Hosted Onboarding as necessary to satisfy
eventually_due requirements as described in step 1. You can use this as a signal of when to send your user back into the flow. Keep in mind that using Hosted Onboarding means you don’t really need to worry about what the requirements are – sending the user back into Hosted Onboarding means it will collect the right information.
For example, if your user mistypes their information and cannot be verified, they could be asked to provide an Identity Document (e.g. a Driver’s License in the United States). Sending this user into Hosted Onboarding prompts them to upload such a document to ensure they become verified.
Step 5: Handle the case of user-initated updates
Most Hosted Onboarding usage discussed thus far has been about prompting the user to provide new information. Hosted Onboarding also supports user-initated updates to the information they’ve already provided via the
type parameter of the Account Link.
type accepts one of two values:
This value for
type provides a form for inputting outstanding requirements. Use it when you’re onboarding a new user, or when an existing user has new requirements; such as when a user had already provided enough information, but you requested a new capability that needs additional info. Send the user to the form in this mode to just collect the new information you need.
This value for
type displays the fields that are already populated on the account object, and allows your user to edit previously provided information. Provide an access point in your platform’s dashboard to a
type=custom_account_update Account Link, for users to initiate updates themselves (e.g., when their address changes). Consider framing this as “edit my profile” or “update my verification information”.
Was this page helpful?