API onboarding
Build your own onboarding flow using Stripe's APIs.
With API onboarding, you use the Accounts API to build an onboarding flow, reporting functionality, and communication channels for your users. Stripe can be completely invisible to the account holder.
Your platform is responsible for all interactions with your users and for collecting all the information needed to verify the account. Verification requirements are updated as laws and regulations change around the world.
Caution
You must plan on reviewing and updating onboarding requirements at least every six months. To avoid that maintenance of your onboarding UI, use Stripe-hosted onboarding or Embedded onboarding.
Establish requirements![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
The following factors affect the onboarding requirements for your connected accounts:
- The origin country of the connected accounts
- The service agreement type applicable to the connected accounts
- The capabilities requested for the connected accounts
- The business type (for example, individual or company) and company.structure (for example, public corporation or private partnership)
Use the interactive form to see how changing these factors affects the requirements.
Requirements form![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Create forms to collect informationClient-side![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
As a best practice, organise the required parameters into logical groupings or forms in your onboarding flow. You might wish to encode a mapping between the Stripe parameters and the logical groupings. Suggested logical groupings for parameters are shown in the first column of the example requirements table.
After you encode the required parameters into your application, generate UIs for the parameters corresponding to these requirements. For each parameter, design a UI form that includes:
- Parameter label, localised for each supported country and language
- Parameter description, localised for each supported country and language
- Parameter input fields with data validation logic and document uploading where required
It’s important to architect your application logic to account for the possibility of additional parameters in the future. For example, Stripe might introduce new parameters, new verifications, or new thresholds that you must incorporate into your onboarding flows over time.
Changing any of the factors that determine your connected accounts requirements means you must also adjust your collection forms. Country and service agreement type are immutable, while capabilities and business type are mutable.
- To change an immutable field such as country or service agreement type, create a new connected account with the new values. Doing so produces new requirements for you to incorporate in your collection flows.
- To change a mutable field such as capabilities or business type, update the connected account. Doing so produces new requirements for you to incorporate in your collection flows.
Include Stripe Terms of Service Agreement![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Your connected accounts must accept Stripe terms of service before they can be activated. You can wrap Stripe terms of service in your own terms of service.
Create a connected accountServer-side![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Create a connected account where your platform is liable for negative balances, Stripe collects fees from your platform account, and your connected accounts don’t have access to a Stripe-hosted dashboard. Request any capabilities that your connected accounts need. Include business type and any other information matching your requirements if you have it available to prefill.
Alternatively, you can create a connected account with type
set to custom
and desired capabilities.
If you don’t specify the country and service type agreement, they’re assigned the following default values:
- The
country
defaults to the same country as your platform. - The service type agreement (
tos_
) defaults toacceptance. service_ agreement full
.
Determine the information to collectServer-side![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
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_
requirements for the account, while incremental onboarding only collects the currently_
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 minimise any impact to connected accounts, requirements might change over time.
To implement your onboarding strategy, inspect the requirements hash of the connected account you created. The requirements hash provides a complete list of parameters you must collect to activate the connected account.
- For incremental onboarding, inspect the
currently_
field in the requirements hash and build an onboarding flow that only collects for the listed parameters.due - For upfront onboarding, inspect the
eventually_
field in the requirements hash and build an onboarding flow that collects for all the listed parameters.due
{ ... "requirements": { "alternatives": [], "current_deadline": null, "currently_due": [ "business_profile.product_description", "business_profile.support_phone", "business_profile.url", "external_account", "tos_acceptance.date", "tos_acceptance.ip" ], "disabled_reason": "requirements.past_due", "errors": [], "eventually_due": [ "business_profile.product_description", "business_profile.support_phone", "business_profile.url", "external_account", "tos_acceptance.date", "tos_acceptance.ip" ], "past_due": [], "pending_verification": [] }, ... }
Update the connected accountServer-side![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Update the connected account object with new information as your user progresses through each step of the onboarding flow to allow Stripe to validate the information as soon as it’s added. After Stripe confirms acceptance of our terms of service, any changes to the connected account triggers reverification. For example, if you change the connected account’s name and ID number, Stripe reruns verifications.
When updating a connected account, you must handle any verification errors or HTTP error codes.
Handle verification errorsServer-side![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
When the connected account’s data is submitted, Stripe verifies it. This process might take minutes or hours depending on the nature of the verification required. During this process, the capabilities you requested have a pending status.
Review status![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
You can retrieve the status of your connected account’s capabilities by:
- Inspecting the Account object’s capabilities hash for the relevant capability.
- Requesting capabilities directly from the Capabilities API and inspecting the status of the relevant capability.
- Listening for
account.
events in your webhook endpoint and inspecting theupdated capabilities
hash for the relevant capability.
After verifications are complete, the capability becomes active
and available to the connected account. Account verifications run continuously, and if a future verification fails, a capability can transition out of active
. Listen for account.
events to detect changes to capability states.
Confirm that your Connect integration is compliant and operational by checking that the account’s charges_
and payouts_
are both true. You can use the API or listen for account.
events. For details on other relevant fields, check the account’s requirements hash. You can’t confirm the integration based on a single value because statuses can vary depending on the application and related policies.
- charges_enabled confirms that your full charge path including the charge and transfer works correctly and evaluates if either
card_
orpayments transfers
capabilities are active. - payouts_enabled evaluates whether your connected account can pay out to an external account. Depending on your risk policies, you can allow your connected account to start transacting without payouts enabled. You must eventually enable payouts to pay your connected accounts.
You can use the following logic as a starting point for defining a summary status to display to your connected account.
Note
You can’t use the API to respond to Stripe risk reviews. You can enable your connected accounts to respond using embedded components, Stripe-hosted onboarding, or remediation links. You can also use the Dashboard to respond to risk reviews on behalf of your connected accounts.
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_
.
Create a form with clear instructions that the account can use to correct the information. Notify the account, then submit the corrected information using the Accounts API.
If you plan to create custom flows to handle all your verification errors:
- Review the details regarding all possible verification errors and how to handle them.
- Test verification states.