Onboard your connected account

As the platform, you must decide if you want to collect the required information from your connected accounts up front or incrementally. Up-front onboarding collects the eventually_due requirements for the account, while incremental onboarding only collects the currently_due requirements.

To determine whether to use up-front or incremental onboarding, review the requirements 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 using the collection_options parameter. To collect the account’s future requirements, set collection_options.future_requirements to include.

Create an Account Link using the connected account ID and include a use_case.account_onboarding.refresh_url and a use_case.account_onboarding.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 -X POST https://api.stripe.com/v2/core/account_links \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-09-30.preview" \
  --json '{
    "account": 
"{{CONNECTED_ACCOUNT_ID}}",
    "use_case": {
        "type": "account_onboarding",
        "account_onboarding": {
            "configurations": [
                "recipient"
            ],
            "refresh_url": "https://example.com/reauth",
            "return_url": "https://example.com/return"
        }
    }
  }'

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.

Set up your integration to listen for changes to account requirements. You can test handling new requirements (and how they might disable charges and payouts) with the test 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 that affect your connected accounts. You can proactively collect this information by reviewing your accounts’ requirements that have a 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 or Account Session.

Accounts store identity information in the identity hash.

Handle verification errors

Listen to the v2.core.account[requirements].updated event. If the account contains any requirements with a 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.

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.

Return URL

Stripe redirects the connected account back to the 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 and checking the 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 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.

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 is active. If the status isn’t active and 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.

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