Skip to content
Create account
or
Sign in
The Stripe Docs logo
/
Ask AI
Create account
Sign in
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Developer tools
Get started
Payments
Finance automation
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Overview
Get started with Connect
Integration fundamentals
Example integrations
Onboard accounts
Configure account Dashboards
    Get started with Connect embedded components
    Customize Connect embedded components
    Supported Connect embedded components
      Available Components
      Account management
      Account onboarding
      Balances
      Documents
      Financial account
      Financial account transactions
      Issuing card
      Issuing cards list
      Notification banner
      Payment details
      Payments
      Payouts
      Payouts list
      Tax registrations
      Tax settings
      Preview components
      App install
      App viewport
      Capital financing
      Capital financing application
      Capital financing promotion
      Disputes for a payment
      Export Tax Transactions
      Payment method settings
      Reporting chart
    Stripe Dashboard customization
    Platform controls for Stripe Dashboard accounts
    Express Dashboard
Accept payments
Pay out to accounts
Manage your Connect platform
Tax forms for your Connect platform
Work with connected account types
HomePlatforms and marketplacesConfigure account DashboardsSupported Connect embedded components

Account onboarding

Use the Account onboarding Connect embedded component.

Copy page

The Account onboarding component uses the Accounts API to read requirements and generate an onboarding form that’s localized for all Stripe-supported countries and that validates data. In addition, Embedded onboarding handles all business types, various configurations of company representatives, document uploads, identity verification, and verification statuses.

For more information, see Embedded onboarding.

Requirements collection options

With embedded onboarding, you can control the collection of currently_due or eventually_due requirements, along with the inclusion of future requirements. You can customize this behavior by using the collectionOptions attribute when integrating the account onboarding component.

External account collection

Use the external_account_collection feature to control whether the component collects external account information. This parameter is enabled by default, and only platforms responsible for collecting updated information when requirements are due or change (including Custom accounts) can disable it. When external_account_collection is enabled, user authentication is required. You can opt out of Stripe user authentication with the disable_stripe_user_authentication parameter.

Disable Stripe user authentication

Use the disable_stripe_user_authentication feature to control whether the component requires Stripe user authentication. The default value is the opposite of the external_account_collection value. For example, if you don’t set external_account_collection, it defaults to true and disable_stripe_user_authentication defaults to false. This value can only be true for accounts where controller.requirement_collection is application.

We recommend implementing 2FA or equivalent security measures as a best practice. For account configurations that support this feature, such as Custom accounts, you assume liability for connected accounts if they can’t pay back negative balances.

Customize 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.

Create an Account Session

When creating an Account Session, enable account onboarding by specifying account_onboarding in the components parameter.

Command Line
cURL
curl https://api.stripe.com/v1/account_sessions \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d account=
{{CONNECTED_ACCOUNT_ID}}
\ -d "components[account_onboarding][enabled]"=true

After creating the Account Session and initializing ConnectJS, you can render the Account onboarding component in the front end:

account-onboarding.js
JavaScript
// Include this element in your HTML const accountOnboarding = stripeConnectInstance.create('account-onboarding'); accountOnboarding.setOnExit(() => { console.log('User exited the onboarding flow'); }); container.appendChild(accountOnboarding); // Optional: make sure to follow our policy instructions above // accountOnboarding.setFullTermsOfServiceUrl('{{URL}}') // accountOnboarding.setRecipientTermsOfServiceUrl('{{URL}}') // accountOnboarding.setPrivacyPolicyUrl('{{URL}}') // accountOnboarding.setSkipTermsOfServiceCollection(false) // accountOnboarding.setCollectionOptions({ // fields: 'eventually_due', // futureRequirements: 'include', // }) // accountOnboarding.setOnStepChange((stepChange) => { // console.log(`User entered: ${stepChange.step}`); // });
MethodTypeDescriptionDefault
setFullTermsOfServiceUrlstringAbsolute URL to your full terms of service agreement.Stripe’s full service agreement
setRecipientTermsOfServiceUrlstringAbsolute URL to your recipient terms of service agreement.Stripe’s recipient service agreement
setPrivacyPolicyUrlstringAbsolute URL to your privacy policy.Stripe’s privacy policy
setSkipTermsOfServiceCollectionstringIf true, embedded onboarding skips terms of service collection and you must collect terms acceptance yourself.false
setCollectionOptions{ fields: 'currently_due' | 'eventually_due', future_requirements: 'omit' | 'include' }Customizes collecting currently_due or eventually_due requirements and controls whether to include future requirements. Specifying eventually_due collects both eventually_due and currently_due requirements.{fields: 'currently_due', futureRequirements: 'omit'}
setOnExit() => voidThe connected account has exited the onboarding process
setOnStepChange({step}: StepChange) => voidThe connected account has navigated from one step to another within the onboarding process. Use StepChange to identify the current step, as described below.

To use this component to set up new accounts:

  1. Create a connected account. You can prefill information on the Account object in this API call.
  2. Initialize Connect embedded components using the ID of the connected account.
  3. Include the account-onboarding element to show the onboarding flow to the connected account.
  4. Listen for the exit event emitted from this component. Stripe sends this event when the connected account exits the onboarding process.
  5. When exit triggers, retrieve the Account details to check the status of:
    • details_submitted
    • charges_enabled
    • payouts_enabled
    • Any other requested capabilities
    If all required capabilities are enabled, you can take the connected account to the next step of your flow.

The StepChange object

The StepChange type is defined in connect.js. 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_type
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 nameDescription
stripe_user_authenticationUser authentication includes a popup to a Stripe-owned window. The connected account must authenticate before they can continue their workflow.
risk_interventionGuides the connected account to resolve risk-related requirements.
legal_entity_sharingConnected accounts can optionally reuse business information from existing accounts with the same owner.
business_typeSets the business type of the connected account. In certain cases the connected account can also set their country.
business_detailsCollects information related to the connected account’s business.
business_verificationCollects 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_bank_account_ownership_verificationCollects 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_documentsCollects other documents and verification requirements related to the business.
representative_detailsCollects information about the account representative.
representative_documentCollects a government-issued ID verifying the existence of the account representative.
representative_additional_documentCollects an additional document to verifying the details of the account representative.
legal_guardian_detailsCollects the legal guardians consent for accounts opened by minors.
ownersCollects information about the beneficial owners of a company.
directorsCollects information about the directors of a company.
executivesCollects information about the executives of a company.
proof_of_ownership_documentCollects documentation that verifies a company’s beneficial owners.
proof_of_authorizationCollects documentation to verify that the account representative holds a position of sufficient authority within a company.
confirm_ownersAllows connected accounts to attest that the beneficial owner information provided to Stripe is both current and correct.
risa_compliance_survey(Applies only to businesses in Japan.) Answers questions concerning the Revised Installment Sales Act.
treasury_and_card_issuing_terms_of_serviceCollects Treasury and Card Issuing terms of service when requesting those capabilities.
external_accountCollects the external account of the connected account.
support_detailsCollects information that helps customers recognize the connected accounts business. This support information can be visible in payment statements, invoices, and receipts.
climateAllows a connected account to opt into Stripe Climate.
taxAllows a connected account to opt into Stripe Tax.
summaryFinal 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_riskFrom the summary step, a connected account can update information related to risk requirements.
summary_business_typeFrom the summary step, a connected account can update information related to their business type.
summary_businessFrom the summary step, a connected account can update information related to their business.
summary_supportFrom the summary step, a connected account can update public-facing information related to their business.
summary_personsFrom the summary step, a connected account can update information about each person on their account.
summary_external_accountFrom the summary step, a connected account can update information related to their external account.
summary_taxFrom the summary step, a connected account can update information related to their Stripe Tax integration.
summary_tax_identification_formFrom 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_climateFrom the summary step, a connected account can update information related to their Stripe Climate integration.
Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access program.
Check out our changelog.
Questions? Contact Sales.
LLM? Read llms.txt.
Powered by Markdoc