Onboarding completes an account’s Requirements so its capabilities can be enabled. There are two ways to do it. They collect the same information.
Hosted account link
POST /v1/accounts/{account_id}/account-links · scope connected_accounts:write · full field reference →
type is onboarding for a new account or update to collect more from an existing one. The account lands on return_url when it finishes or leaves, and on refresh_url when the link is no longer usable, where your handler creates a new link and redirects again.
Creating a link supersedes the previous one, reported as previous_link_superseded. A link generated on every page render invalidates the one you sent earlier. Create a link when the account is about to use it.
The return redirect does not confirm completion. It fires whether the account finished or abandoned the flow, and is lost if the browser never returns. Confirm from account.updated and capability.updated. See Connect events.
API onboarding
Read the account’s requirements, render them, collect the values, and submit. Every endpoint is under /v1/accounts/{account_id}/ and takes an API key. Documents are the exception: they are collected through an account link, in the hosted flow. See Onboard through the API.
Requirements change as regulation changes. On the hosted link those changes appear on their own; here a new requirement is a field your interface does not render, and accounts stall. Budget for maintaining this.
Finishing
A capability is enabled on review, not when a form is submitted. Subscribe to capability.updated and unlock the account’s features when it arrives. See Monitor onboarding.
