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