# Onboard your connected account

Onboard your connected accounts to your marketplace.

After you [create and prefill a connected account](https://docs.stripe.com/connect/marketplace/tasks/create.md), create an [Account Link](https://docs.stripe.com/api/v2/core/account-links.md) and send it to the account user so they can complete the onboarding process. An Account Link is a single-use URL that a connected account uses to access the Connect onboarding flow.

Alternatively, you can also build out a custom onboarding flow using [embedded components](https://docs.stripe.com/connect/get-started-connect-embedded-components.md) or the [API](https://docs.stripe.com/connect/api-onboarding.md). To streamline compliance and maintenance, use Account Links or create your own onboarding flow with embedded components. This guide uses Account Links.

The Connect onboarding flow doesn’t ask your connected account for any information that you [prefilled](https://docs.stripe.com/connect/marketplace/tasks/create.md#prefill-account-information). However, it does ask the connected account to confirm the prefilled information before they accept the [Connect service agreement](https://docs.stripe.com/connect/service-agreement-types.md).

> Stripe-hosted onboarding is only supported in web browsers. You can’t use it in embedded web views inside mobile or desktop applications.

## 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 minimize any impact to connected accounts, requirements might change over time.

For connected accounts where you’re responsible for requirement collection, you can customize the behavior 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`.

## Create an Account Link

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/marketplace/tasks/onboard.md#refresh-url) and a [use_case.account_onboarding.return_url](https://docs.stripe.com/connect/marketplace/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 them to the return URL when they have completed or exited the onboarding flow.

Additionally, based on whether you want to collect all information up front or collect it incrementally, pass either `eventually_due` or `currently_due` in `use_case.account_onboarding.collection_options.fields`. This example passes `eventually_due` to use up-front onboarding for both `currently_due` and `eventually_due` requirements. For incremental onboarding, pass `currently_due` to collect only `currently_due` requirements up front.

```curl
curl -X POST https://api.stripe.com/v2/core/account_links \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-03-25.preview" \
  --json '{
    "account": "{{CONNECTEDACCOUNT_ID}}",
    "use_case": {
        "type": "account_onboarding",
        "account_onboarding": {
            "configurations": [
                "recipient"
            ],
            "refresh_url": "https://example.com/reauth",
            "return_url": "https://example.com/return"
        }
    }
  }'
```

| Parameter                                                                                                                                                                    | Value                           | Description                                                                                                                                                                                                                      |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [account](https://docs.stripe.com/api/v2/core/account-links/create.md#v2_create_account_links-account)                                                                       | The ID of the connected account | Set this to the ID of the connected account you’re creating an Account Link for.                                                                                                                                                 |
| [use_case.type](https://docs.stripe.com/api/v2/core/account-links/create.md#v2_create_account_links-use_case-type)                                                           | `account_onboarding`            | Provides a form to collect any required information.                                                                                                                                                                             |
| [use_case.account_onboarding.configurations](https://docs.stripe.com/api/v2/core/account-links/create.md#v2_create_account_links-use_case-account_onboarding-configurations) | `recipient`                     | Sets the configurations for the connected account. In this case, the `recipient` configuration means that you can pay out funds to the connected account.                                                                        |
| [use_case.account_onboarding.return_url](https://docs.stripe.com/api/v2/core/account-links/create.md#v2_create_account_links-use_case-account_onboarding-return_url)         | A valid URL                     | The URL to redirect the user to after they leave or complete the onboarding flow.                                                                                                                                                |
| [use_case.account_onboarding.refresh_url](https://docs.stripe.com/api/v2/core/account-links/create.md#v2_create_account_links-use_case-account_onboarding-refresh_url)       | A valid URL                     | The URL to redirect the user to if the Account Link expired, was previously visited, or is otherwise invalid. Use this URL to generate a new Account Link with the same parameters you used to create the original Account Link. |

### Send your connected account to the onboarding flow 

Provide the Account Link URL to send your connected account to the onboarding flow. Each Account Link URL can only be used once, because it grants access to the account holder’s personal information.

> Don’t email, text, or otherwise send account link URLs outside of your platform application. Instead, provide them to the authenticated account holder within your application.

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

> #### Migrate a marketplace from Accounts v1 to Accounts v2
> 
> For new accounts, create an event destination to [listen for v2.core.account[requirements].updated events](https://docs.stripe.com/connect/marketplace/tasks/onboard.md#handle-account-updates). Your existing connected accounts fire both v1 and v2 events, so your integration can manage them by listening for `v1.account.updated` v2 events instead of `account.updated` v1 events.

### 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/marketplace/tasks/onboard)
## Handle the user returning to your platform

Connect onboarding requires you to pass both a `return_url` and `refresh_url` to handle all cases where the user is redirected to your platform. It’s important that you implement these correctly to provide the best experience for your user.

> You must use HTTPS for your `return_url` and `refresh_url`, both in production and in testing environments (for example, to test with localhost). The Account Link creation process fails if you use HTTP.

### Return URL 

Stripe redirects the connected account back to the [return_url](https://docs.stripe.com/api/v2/core/account-links/create.md#v2_create_account_links-use_case-account_onboarding-return_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 by either:

- [Retrieving the account](https://docs.stripe.com/api/v2/core/accounts/retrieve.md) and checking the [requirements](https://docs.stripe.com/api/v2/core/accounts/retrieve.md#v2_retrieve_accounts-response-requirements) hash for outstanding requirements.
- Caching the account’s status in your application and keeping it updated by listening to the `v2.core.account[requirements].updated` event.

If onboarding is incomplete, provide prompts in your application to allow the account to continue onboarding later.

### Refresh URL 

Stripe redirects the account user to the [refresh_url](https://docs.stripe.com/api/v2/core/account-links/create.md#v2_create_account_links-use_case-account_onboarding-refresh_url) in the following cases:

- The link expired (a few minutes elapsed after the link was created).
- The user already visited the URL (the user refreshed the page or clicked back or forward in the browser).
- Your platform is no longer able to access the account.
- 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.
- The account has been rejected.

Configure the `refresh_url` to call a method on your server to create a new Account Link with the same parameters, then redirect the connected account to the new Account Link URL.

## Handle users who haven't completed onboarding

An account user who gets redirected to your `return_url` might not have completed the onboarding process. Use the `/v2/core/accounts` endpoint to retrieve the `Account`and check whether [configuration.recipient.capabilities.stripe_balance.stripe_transfers.status](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-configuration-recipient-capabilities-stripe_balance-stripe_transfers-status) is `active`. If the status isn’t `active` and [configuration.recipient.capabilities.stripe_balance.stripe_transfers.status_details.code](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-configuration-recipient-capabilities-stripe_balance-stripe_transfers-status_details-code) is `requirements_past_due`, provide UI prompts to allow the account user to continue onboarding through a new Account Link. Handle other codes as needed.

## Handle connected account 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.

When you create an Account Link, set the `type` to `account_onboarding`. Account Links of this type provide a form for inputting any outstanding requirements. Use it when you’re onboarding a new connected account, or when an existing account has new requirements (such as when you request a new capability that needs additional information).

## Next steps

When your connected account is active, [enable the payment methods](https://docs.stripe.com/connect/marketplace/tasks/enable-payment-methods.md) that you want to support.