# Onboard your connected account Choose between Stripe-hosted or embedded onboarding to collect requirements from your connected accounts. After you create a connected account on your platform, you must provide a way for the account to complete onboarding requirements. You can use **Stripe-hosted onboarding** (redirect to Stripe) or **Embedded onboarding** (stay in your app). | | Stripe-hosted onboarding | Embedded onboarding | | ---------------------------------- | -------------------------------------------- | -------------------------------------------------------------- | | **Integration effort** | Low – redirect to Stripe, no UI to build | Medium – render the `account-onboarding` component in your app | | **Onboarding flow** | Redirect to a Stripe-hosted page | Stays within your platform; supports theming | | **Mobile and desktop app support** | Doesn’t work in embedded web views | Supported through iOS and Android SDKs | | **Recommendation** | Use when you want minimal integration effort | Use when you want a branded, in-app onboarding | #### Stripe-hosted onboarding > Stripe-hosted onboarding is only supported in web browsers. You can’t use it in embedded web views inside mobile or desktop applications. ## Determine the information to collect As the platform, you must decide if you want to collect the required information from your connected accounts *up front* (Upfront onboarding is a type of onboarding where you collect all required verification information from your users at sign-up) or *incrementally* (Incremental onboarding is a type of onboarding where you gradually collect required verification information from your users. You collect a minimum amount of information at sign-up, and you collect more information as the connected account earns more revenue). Up-front onboarding collects the `eventually_due` requirements for the account, while incremental onboarding only collects the `currently_due` requirements. | Onboarding type | Advantages | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Up-front** | - Normally requires only one request for all information - Avoids the possibility of payout and processing issues due to missed deadlines - Exposes potential risk early when accounts refuse to provide information | | **Incremental** | - Accounts can onboard quickly because they don’t have to provide as much information | To determine whether to use up-front or incremental onboarding, review the [requirements](https://docs.stripe.com/connect/required-verification-information.md) for your connected accounts’ locations and capabilities. While Stripe tries to minimise any impact to connected accounts, requirements might change over time. For connected accounts where you’re responsible for requirement collection, you can customise the behaviour of [future requirements](https://docs.stripe.com/connect/handle-verification-updates.md) using the `collection_options` parameter. To collect the account’s future requirements, set [collection_options.future_requirements](https://docs.stripe.com/api/v2/core/account-links/create.md#create_account_links-collection_options-future_requirements) to `include`. ### Collect additional public details Stripe collects the required public details for each connected account. You can choose additional fields to collect during onboarding according to your business needs. Any fields you choose that Stripe doesn’t require appear as optional, and connected accounts can choose whether to provide them. 1. In the [Public details](https://dashboard.stripe.com/settings/connect/onboarding-options/public-details) settings in the Dashboard, enable the **Collect public details** toggle. 1. Select the fields to show to connected accounts during onboarding. 1. Click **Save**. #### Available fields You can collect the following public details: | Field | Description | | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | [Statement descriptor](https://docs.stripe.com/connect/statement-descriptors.md) | The text that appears on a customer’s credit card or bank statement for payments made to the connected account. | | Customer support phone number | A phone number customers can call for support related to the connected account. | | Customer support address | A mailing address customers can use to contact the connected account. | | Customer support email | An email address customers can use to contact the connected account. | > #### Requirements vary > > Stripe’s requirements vary by connected account based on their business type, country, and requested capabilities. Enable fields to make sure they always appear during onboarding, whether or not they’re required. ## Create an Account Link [Server-side] Create an [Account Link](https://docs.stripe.com/api/v2/core/account-links/create.md) using the connected account ID and include a [use_case.account_onboarding.refresh_url](https://docs.stripe.com/connect/saas/tasks/onboard.md#refresh-url) and a [use_case.account_onboarding.return_url](https://docs.stripe.com/connect/saas/tasks/onboard.md#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 `use_case.account_onboarding.collection_options.fields`. This example passes `eventually_due` to use up-front onboarding. For incremental onboarding, set it to `currently_due`. ```curl curl -X POST https://api.stripe.com/v2/core/account_links \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-04-22.preview" \ --json '{ "account": "{{CONNECTEDACCOUNT_ID}}", "use_case": { "type": "account_onboarding", "account_onboarding": { "collection_options": { "fields": "eventually_due" }, "configurations": [ "merchant" ], "return_url": "https://example.com/return", "refresh_url": "https://example.com/refresh" } } }' ``` ### 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. ## Identify and address requirement updates [Server-side] Set up your integration to [listen for changes](https://docs.stripe.com/connect/handling-api-verification.md#verification-process) to account requirements. You can test handling new requirements (and how they might disable charges and payouts) with the [test trigger cards](https://docs.stripe.com/connect/testing.md#trigger-cards). Send a connected account back through onboarding when it has any `currently_due` or `eventually_due` requirements. You don’t need to identify the specific requirements, because the onboarding interface knows what information it needs to collect. For example, if a typo is preventing verification of the account owner’s identity, onboarding prompts them to upload an identity document. Stripe notifies you about any [upcoming requirements updates](https://support.stripe.com/user/questions/onboarding-requirements-updates) that affect your connected accounts. You can proactively collect this information by reviewing your accounts’ requirements that have a [requested_reasons.code](https://docs.stripe.com/api/v2/core/accounts/retrieve.md#v2_retrieve_accounts-response-requirements-entries-requested_reasons-code) of `future_requirements`. For connected accounts where Stripe is responsible for collecting requirements, stop receiving updates for identity information after creating an [Account Link](https://docs.stripe.com/api/v2/core/account-links.md) or [Account Session](https://docs.stripe.com/api/account_sessions.md). Accounts store identity information in the `identity` hash. > #### Account v2 webhook event change > > For Account v2, create an event destination to [listen for v2.core.account[requirements].updated events](https://docs.stripe.com/connect/saas/tasks/onboard.md#account-update) instead of the `account.updated` v1 event. ### Handle verification errors Listen to the [v2.core.account[requirements].updated](https://docs.stripe.com/api/v2/core/events/event-types.md?api-version=preview) event. If the account contains any requirements with a [minimum_deadline.status](https://docs.stripe.com/api/v2/core/accounts/retrieve.md#v2_retrieve_accounts-response-requirements-entries-minimum_deadline-status) of `currently_due` when the deadline arrives, the corresponding functionality is disabled and those statuses become `past_due`. Let your accounts remediate their verification requirements by directing them to the Stripe-hosted onboarding form. (See full diagram at https://docs.stripe.com/connect/saas/tasks/onboard) ## Handle the connected account returning to your platform [Server-side] 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. > You can use HTTP for your `refresh_url` and `return_url` while you’re in a testing environment (for example, to test locally), but live mode only accepts HTTPS. You must update any testing URLs to HTTPS URLs before you go live. ### Refresh URL Your connected account is redirected to the `refresh_url` when: - The link 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 an Account Link to expire. Configure the `refresh_url` to 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 doesn’t 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. This URL passes no state. After redirecting a connected account to the `return_url`, determine whether the account completed onboarding. [Retrieve the account](https://docs.stripe.com/api/v2/core/accounts/retrieve.md) and check the [requirements](https://docs.stripe.com/api/v2/core/accounts/retrieve.md#v2_retrieve_accounts-response-requirements) hash for outstanding requirements. Alternatively, listen to the `v2.core.account[requirements].updated` event sent to your webhook endpoint and cache the state of the account in your application. If onboarding is incomplete, provide prompts in your application to allow them to continue onboarding later. ## Handle connected account-initiated updates [Server-side] Stripe-hosted onboarding also supports connected account-initiated updates to the information they’ve already provided. Listen to the `v2.core.account[requirements].updated` event sent to your webhook endpoint to be notified when the account completes requirements and updates their information. When you create an Account Link, you can set the `type` to either `account_onboarding` or `account_update`. > #### Account Link type restriction > > You can create Account Links of type `account_update` only for connected accounts where your platform is responsible for collecting requirements, including Custom accounts. You can’t create them for accounts that have access to a Stripe-hosted Dashboard. If you use [Connect embedded components](https://docs.stripe.com/connect/get-started-connect-embedded-components.md), you can include components that allow your connected accounts to update their own information. For an account without Stripe-hosted Dashboard access where Stripe is liable for negative balances, you must use embedded components. ### Account Links for 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 information). Send them to this type of Account Link to just collect the new information you need. ### Account Links for 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 allow the connected account to edit previously provided information. Provide an option in your application (for example, “edit my profile” or “update my verification information”) for connected accounts to make updates themselves. #### Embedded onboarding Accounts v2 supports [networked onboarding](https://docs.stripe.com/connect/networked-onboarding.md). Owners of multiple Stripe accounts can automatically share business information between them. Embedded onboarding uses the [Accounts v2 API](https://docs.stripe.com/api/v2/core/accounts.md) to read the requirements and generate an onboarding form with data validation, localised for all Stripe-supported countries. In addition, embedded onboarding handles all: - Business types - Configurations of company representatives - Verification document uploading - Identity verification and statuses - International bank accounts - Error states This demo lets you explore the embedded onboarding component’s interface: Note: The following is a preview/demo component that behaves differently than live mode usage with real connected accounts. The actual component has more functionality than what might appear in this demo component. For example, for connected accounts without Stripe dashboard access (custom accounts), no user authentication is required in production. ## Create an account and configure information collection [Server-side] For each connected account, use the Accounts v2 API to [create an Account object](https://docs.stripe.com/api/v2/core/accounts/create.md) with the `merchant` configuration. If you want to charge your connected accounts using subscriptions, also assign the `customer` configuration. To assign a configuration, simply include it in a create or update call. You don’t have to request any of its capabilities. If you specify the account’s country or request any capabilities for it, then the account owner can’t change its country. Otherwise, it depends on the account’s Dashboard access: - **Full Stripe Dashboard:** During onboarding, the account owner can select any acquiring country, the same as when signing up for a normal Stripe account. Stripe automatically requests a set of capabilities for the account based on the selected country. - **Express Dashboard:** During onboarding, the account owner can select from a list of countries that you configure in your platform Dashboard [Onboarding options](https://dashboard.stripe.com/settings/connect/onboarding-options/countries). You can also configure those options to specify the default capabilities to request for accounts in each country. - **No Stripe Dashboard**: If Stripe is responsible for collecting requirements, then the onboarding flow lets the account owner select any acquiring country. Otherwise, your custom onboarding flow must set the country and request capabilities. > #### Use include to populate objects in the response > > When you create, retrieve or update an `Account` in API v2, certain properties are only populated in the response if you specify them [in the include parameter](https://docs.stripe.com/api-includable-response-values.md). For any of those properties that you don’t specify, the response includes them as null, regardless of their actual value. ```curl curl -X POST https://api.stripe.com/v2/core/accounts \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-04-22.preview" \ --json '{ "contact_email": "furever_contact@example.com", "display_name": "Furever", "dashboard": "full", "identity": { "business_details": { "registered_name": "Furever" }, "country": "us", "entity_type": "company" }, "configuration": { "customer": {}, "merchant": { "capabilities": { "card_payments": { "requested": true } } } }, "defaults": { "currency": "usd", "responsibilities": { "fees_collector": "stripe", "losses_collector": "stripe" }, "locales": [ "en-US" ] }, "include": [ "configuration.customer", "configuration.merchant", "identity", "requirements" ] }' ``` The response includes the ID, which you use to reference the `Account` throughout your integration. ### Request capabilities You can request [capabilities](https://docs.stripe.com/connect/account-capabilities.md#creating) when creating an account by setting the desired capabilities’ `requested` property to true. For accounts with access to the Express Dashboard, you can also configure your [Onboarding options](https://dashboard.stripe.com/settings/connect/onboarding-options/countries) to automatically request certain capabilities when creating an account. Stripe’s onboarding UIs automatically collect the requirements for requested capabilities. To reduce onboarding effort, request only the capabilities you need. ### Pre-fill information If you have information about the account holder (such as their name, address, or other details), you can simplify onboarding by providing it when you create or update the account. The onboarding interface asks the account holder to confirm the pre-filled information before accepting the [Connect service agreement](https://docs.stripe.com/connect/service-agreement-types.md). The account holder can edit any pre-filled information before they accept the service agreement, even if you provided the information using the Accounts API. If you onboard an account and your platform provides it with a URL, prefill the account’s [defaults.profile.business_url](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-defaults-profile-business_url). If the business doesn’t have a URL, you can prefill its [defaults.profile.product_description](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-defaults-profile-product_description) instead. When testing your integration, use [test data](https://docs.stripe.com/connect/testing.md) to simulate different outcomes including identity verification, business information verification, payout failures, and more. ### Collect a custom set of requirements You can configure the embedded component to collect a specific set of requirements by using the `exclude` and `only` collection options. That allows you to build a custom flow for collecting certain requirements and use the embedded component for all other requirements. For example: - Use `exclude` to prevent connected accounts from accessing the specified requirements through the component. - Use `only` to restrict connected accounts to accessing only the specified requirements through the component. For details about using these collection options, see the documentation for the [account onboarding component](https://docs.stripe.com/connect/supported-embedded-components/account-onboarding.md#requirement-restrictions) or [account management component](https://docs.stripe.com/connect/supported-embedded-components/account-management.md#requirement-restrictions). ## Determine whether to collect all information up front As the platform, you must decide if you want to collect the required information from your connected accounts *up front* (Upfront onboarding is a type of onboarding where you collect all required verification information from your users at sign-up) or *incrementally* (Incremental onboarding is a type of onboarding where you gradually collect required verification information from your users. You collect a minimum amount of information at sign-up, and you collect more information as the connected account earns more revenue). Up-front onboarding collects the `eventually_due` requirements for the account, while incremental onboarding only collects the `currently_due` requirements. | Onboarding type | Advantages | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Up-front** | - Normally requires only one request for all information - Avoids the possibility of payout and processing issues due to missed deadlines - Exposes potential risk early when accounts refuse to provide information | | **Incremental** | - Accounts can onboard quickly because they don’t have to provide as much information | To determine whether to use up-front or incremental onboarding, review the [requirements](https://docs.stripe.com/connect/required-verification-information.md) for your connected accounts’ locations and capabilities. While Stripe tries to minimise any impact to connected accounts, requirements might change over time. For connected accounts where you’re responsible for requirement collection, you can customise the behaviour of [future requirements](https://docs.stripe.com/connect/handle-verification-updates.md) using the `collection_options` parameter. To collect the account’s future requirements, set [collection_options.future_requirements](https://docs.stripe.com/api/v2/core/account-links/create.md#create_account_links-collection_options-future_requirements) to `include`. ### Collect additional public details Stripe collects the required public details for each connected account. You can choose additional fields to collect during onboarding according to your business needs. Any fields you choose that Stripe doesn’t require appear as optional, and connected accounts can choose whether to provide them. 1. In the [Public details](https://dashboard.stripe.com/settings/connect/onboarding-options/public-details) settings in the Dashboard, enable the **Collect public details** toggle. 1. Select the fields to show to connected accounts during onboarding. 1. Click **Save**. #### Available fields You can collect the following public details: | Field | Description | | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | [Statement descriptor](https://docs.stripe.com/connect/statement-descriptors.md) | The text that appears on a customer’s credit card or bank statement for payments made to the connected account. | | Customer support phone number | A phone number customers can call for support related to the connected account. | | Customer support address | A mailing address customers can use to contact the connected account. | | Customer support email | An email address customers can use to contact the connected account. | > #### Requirements vary > > Stripe’s requirements vary by connected account based on their business type, country, and requested capabilities. Enable fields to make sure they always appear during onboarding, whether or not they’re required. ## Customise the policies shown to your users Connected accounts see Stripe’s service agreement and [Privacy Policy](https://stripe.com/privacy) during embedded onboarding. Connected account users who haven’t [accepted Stripe’s services agreement](https://docs.stripe.com/connect/service-agreement-types.md#accepting-the-correct-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](https://stripe.com/privacy). For connected accounts where the platform is responsible for requirement collection, you have additional options to customise 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](https://docs.stripe.com/connect/updating-service-agreements.md#tos-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](https://docs.stripe.com/connect/saas/tasks/onboard.md#link-to-your-own-agreements-and-privacy-policy). ### Link to your agreements and privacy policy Connected accounts see the Stripe service agreement and [Privacy Policy](https://stripe.com/privacy) 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](https://docs.stripe.com/connect/updating-service-agreements.md#adding-stripes-service-agreement-to-your-terms-of-service) and [link to the Stripe Privacy Policy](https://docs.stripe.com/connect/updating-service-agreements.md#disclosing-how-stripe-processes-user-data). ## Integrate the account onboarding component [Server-side] [Client-side] Create an [Account Session](https://docs.stripe.com/api/account_sessions.md) by specifying the ID of the connected account and `account_onboarding` as the component to enable. ### Create an Account Session When [creating an Account Session](https://docs.stripe.com/api/account_sessions/create.md), enable account onboarding by specifying `account_onboarding` in the `components` parameter. ```curl curl https://api.stripe.com/v1/account_sessions \ -u "<>:" \ -d "account={{CONNECTEDACCOUNT_ID}}" \ -d "components[account_onboarding][enabled]=true" ``` ### Render the Account onboarding component After creating the Account Session and [initialising ConnectJS](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#account-sessions), you can render the Account onboarding component in the front end: #### JavaScript ```js // 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', // requirements: { // exclude: ['business_profile.product_description'] // } // }) // accountOnboarding.setOnStepChange((stepChange) => { // console.log(`User entered: ${stepChange.step}`); // }); ``` See [Account onboarding](https://docs.stripe.com/connect/supported-embedded-components/account-onboarding.md) for onboarding features such as: - Attaching handlers like `setOnStepChange` for analytics. - Embedding onboarding in your mobile app with our iOS and Android SDKs. - Customising terms and privacy URLs. - Specifying collection options. ## Identify and address requirement updates [Server-side] Set up your integration to [listen for changes](https://docs.stripe.com/connect/handling-api-verification.md#verification-process) to account requirements. You can test handling new requirements (and how they might disable charges and payouts) with the [test trigger cards](https://docs.stripe.com/connect/testing.md#trigger-cards). Send a connected account back through onboarding when it has any `currently_due` or `eventually_due` requirements. You don’t need to identify the specific requirements, because the onboarding interface knows what information it needs to collect. For example, if a typo is preventing verification of the account owner’s identity, onboarding prompts them to upload an identity document. Stripe notifies you about any [upcoming requirements updates](https://support.stripe.com/user/questions/onboarding-requirements-updates) that affect your connected accounts. You can proactively collect this information by reviewing your accounts’ requirements that have a [requested_reasons.code](https://docs.stripe.com/api/v2/core/accounts/retrieve.md#v2_retrieve_accounts-response-requirements-entries-requested_reasons-code) of `future_requirements`. For connected accounts where Stripe is responsible for collecting requirements, stop receiving updates for identity information after creating an [Account Link](https://docs.stripe.com/api/v2/core/account-links.md) or [Account Session](https://docs.stripe.com/api/account_sessions.md). Accounts store identity information in the `identity` hash. ### Handle verification errors Listen to the [v2.core.account[requirements].updated](https://docs.stripe.com/api/v2/core/events/event-types.md?api-version=preview) event. If the account contains any requirements with a [minimum_deadline.status](https://docs.stripe.com/api/v2/core/accounts/retrieve.md#v2_retrieve_accounts-response-requirements-entries-minimum_deadline-status) of `currently_due` when the deadline arrives, the corresponding functionality is disabled and those statuses become `past_due`. Let your accounts remediate their verification requirements by directing them to the [Account onboarding component](https://docs.stripe.com/connect/supported-embedded-components/account-onboarding.md). (See full diagram at https://docs.stripe.com/connect/saas/tasks/onboard) ### Disable Stripe user authentication When using embedded onboarding, [Stripe user authentication](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#user-authentication-in-connect-embedded-components) is enabled by default. You can use [`disable_stripe_user_authentication`](https://docs.stripe.com/api/account_sessions/create.md#create_account_session-components-account_onboarding-features-disable_stripe_user_authentication) to remove this behaviour. We recommend implementing two-factor authentication or equivalent security measures as a [best practice](https://docs.stripe.com/connect/risk-management/best-practices.md#prevent-account-take-overs). For account configurations that support this feature, such as Custom, you assume liability for connected accounts if they can’t pay back [negative balances](https://docs.stripe.com/connect/risk-management/best-practices.md#decide-your-approach-to-negative-balance-liability). ## Next steps When your connected account is active, [build a payments integration](https://docs.stripe.com/connect/saas/tasks/accept-payment.md) so they can begin accepting payments.