Onboarding Fresh

Onboard connected accounts using Stripe-hosted flows, embedded components, or your own custom API-driven UI.

Onboarding options compared

	Stripe-Hosted	Embedded	API
Integration effort	Minimal	Moderate	High
Customization	Stripe-branded + limited platform branding	Highly themeable	Full control
Auto-updates for new compliance	Yes	Yes	Requires integration changes
Supports new countries without code changes	Yes	Yes	No
Supports legal entity sharing	Yes	Yes	No
Ideal for	Platforms that want Stripe to handle onboarding	Branded in-app onboarding	Full UI control

Stripe-hosted onboarding (recommended)

Stripe hosts the onboarding form. Your platform redirects the connected account to a Stripe-hosted URL. Stripe handles:

• All compliance requirements per country
• Document uploads
• Real-time verification
• Updates when requirements change

Step 1: Create a connected account

# With controller properties (recommended)
curl https://api.stripe.com/v1/accounts \
  -u "sk_test_YOUR_KEY:" \
  -d "controller[fees][payer]=application" \
  -d "controller[losses][payments]=application" \
  -d "controller[stripe_dashboard][type]=express"

# Or with account type
curl https://api.stripe.com/v1/accounts \
  -u "sk_test_YOUR_KEY:" \
  -d type=standard

Store the returned account id — you'll use it to create the Account Link.

Step 2: Create an Account Link

An Account Link is a one-time URL that grants the connected account access to the onboarding form.

curl https://api.stripe.com/v1/account_links \
  -u "sk_test_YOUR_KEY:" \
  -d "account={{CONNECTED_ACCOUNT_ID}}" \
  --data-urlencode "refresh_url=https://example.com/onboard/refresh" \
  --data-urlencode "return_url=https://example.com/onboard/return" \
  -d type=account_onboarding \
  -d "collection_options[fields]=eventually_due"

• collection_options[fields]=eventually_due — up-front onboarding (collects all required info at once)
• collection_options[fields]=currently_due — incremental onboarding (minimum info at signup, more collected later)

Step 3: Redirect to the Account Link URL

Redirect the authenticated account holder to the URL returned in the Account Link response. The URL is single-use and expires after a few minutes — never email or share it outside your application.

Prefill account information

If you have information about the connected account, prefill it to reduce friction:

curl https://api.stripe.com/v1/accounts \
  -u "sk_test_YOUR_KEY:" \
  -d email=seller@example.com \
  -d "business_profile[url]=https://sellersite.com" \
  -d country=US

Handle return URLs

refresh_url — Stripe redirects here when the Account Link has expired or been visited already. Your server should generate a new Account Link and redirect again.

return_url — Stripe redirects here when the connected account exits the onboarding flow (completed or clicked "Save for later"). This does NOT mean onboarding is complete.

After return, retrieve the account and check requirements to confirm status:

curl https://api.stripe.com/v1/accounts/{{CONNECTED_ACCOUNT_ID}} \
  -u "sk_test_YOUR_KEY:"

Check requirements.currently_due — if not empty, the account has outstanding items.

Handle requirement updates

Listen for account.updated webhook events. If requirements.currently_due is non-empty and requirements.current_deadline is approaching, send the account back through onboarding via a new Account Link.

Embedded onboarding

Embed the Account Onboarding component directly in your application. Connected accounts complete onboarding without leaving your site.

• Uses the same Stripe compliance engine as hosted onboarding
• Highly themeable (colors, fonts, border radius)
• Requires creating an Account Session for each session

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

Use the returned client_secret with Stripe.js to mount the component.

API onboarding

Build your own onboarding UI using the Accounts API. You're responsible for:

• Collecting all required fields per country and business type
• Document upload handling
• Real-time verification flows
• Updating your integration as compliance requirements change (at minimum every 6 months)

Not recommended unless you need full UI control and have the resources to maintain it.

Up-front vs incremental onboarding

Type	What it collects	Trade-off
Up-front	All eventually_due requirements at signup	More friction at start, avoids payout interruptions later
Incremental	Only currently_due requirements at signup	Faster signup, risk of future payout/processing issues if requirements are missed

Account Link types

Type	Use case
account_onboarding	New accounts or accounts with new requirements
account_update	Existing accounts that need to update previously provided information

account_update links are only available for accounts where your platform is responsible for requirement collection (Custom accounts). Not available for accounts with Stripe-hosted Dashboard access.