Stripe Connect onboarding: the exact order that does not strand users

TL;DR

Create an AccountLink: pass the account ID, a refresh\url (where Stripe sends the user if the link expires or they abandon), a return\url (where Stripe sends them when done), and type set to account\_onboarding. Onboarding is a handoff between your platform, Stripe, and the account holder. Do the steps out of order and users hit dead links or accounts stall unverified. Subscribe to account.updated from day one (separate skill).

When to use

You are seeing this: Onboarding is a handoff between your platform, Stripe, and the account holder. Use this skill when you run into "Stripe Connect onboarding: the exact order that does not strand users".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Stripe Connect onboarding in order

Onboarding is a handoff between your platform, Stripe, and the account holder. The order is fixed. Do the steps out of order and users hit dead links or accounts stall unverified.

The v1 account-links sequence

1. Create the Account object first, with the capabilities the account will need. You need an account ID before anything else.
2. Create an AccountLink: pass the account ID, a refresh_url (where Stripe sends the user if the link expires or they abandon), a return_url (where Stripe sends them when done), and type set to account_onboarding.
3. Redirect the account holder to the AccountLink URL immediately. Account links expire quickly; do not store them for later.
4. Handle the return: when the user lands on your return_url, do not assume onboarding is complete. Retrieve the Account and check requirements.currently_due and capability statuses.
5. If requirements remain, send them back through a fresh AccountLink. Loop until currently_due is empty and the needed capabilities are active.

Rules that bite

• refresh_url is not optional in practice. Links expire; without a refresh URL the user hits a dead end and you get a support ticket.
• Never show onboarding as "done" based on the return URL alone. Stripe redirects back even when requirements are still outstanding.
• For existing platforms on the Accounts v2 API, the equivalent is embedded components driven by Account Sessions, not hosted links. Do not mix the two patterns in one flow.

After onboarding

Subscribe to account.updated from day one (separate skill). Onboarding is not a one-time event; requirements recur.

Stripe's Connect onboarding docs describe the account-then-account-link sequence with refreshurl and returnurl, and warn that account links are short-lived. The Accounts v2 docs describe embedded components via Account Sessions as the current alternative. Verified against live docs 2026-09-26.