Account onboarding

Requirements collection options

When you collect information using the account onboarding component, it always collects currently_due requirements. You can use the collectionOptions attribute to also request any of the following:

• eventually_due requirements
• future requirements
• Granular requirement restrictions

For more information about specific requirements for your connected accounts, see Required verification information.

Requirement restrictions

While specifying collection options, you can configure granular requirement restrictions as only or exclude. Both options allow specifying an array of strings that represent either currently_due or eventually_due requirements on an account.

Think of the options as filters, where exclude filters out matching account requirements, and only acts as an intersection between the account requirements and the specified values. They also support wildcard matching using * and relationship prefixes.

For example, if you have a connected account with several owners, you can collect the address information for all owners by specifying only: ["owners.address.*"].

A person can have multiple relationships associated to them, and relationships can be assigned to multiple persons. Therefore, when you leverage relationship prefixes, they apply to all persons on the account with the specified relationship. This is especially useful in situations where you don’t know a specific person’s ID, but do know their relationship.

Important considerations:

• Accounts still need to satisfy all KYC requirements in order to have capabilities enabled. The exclude option doesn’t remove a requirement, it only prevents collection at the time. The information must still be collected.
• These restrictions only apply within embedded components. They don’t affect accounts using other types of dashboards.
• This feature is intended for building improved user experiences, not for preventing accounts from accessing information.

only requirement restriction

This option scopes collection to the set of specified requirements that are also outstanding on the account. It’s most commonly used to build a remediation experience, and is particularly useful for requirements that require some form of document upload or identity verification.

This option prevents account onboarding from presenting the standard final summary step. If all of the specified requirements have been provided, the account onboarding component exits immediately.

exclude requirement restriction

This option hides the specified fields, which prevents a connected account from providing or editing that information. It only hides fields from the component; it doesn’t remove information requirements. This option is useful when you want to prefill information that you don’t want the connected account to access during onboarding.

For Express accounts, if you want to exclude the business_type requirement (such as to prevent an account from changing their business type), the account country and capabilities must be set.

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.

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

// 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.setCollectionOptions({
//   fields: 'eventually_due',
//   futureRequirements: 'include',
// })
// accountOnboarding.setOnStepChange((stepChange) => {
//   console.log(`User entered: ${stepChange.step}`);
// });