Skip to main content
In this guide you’ll create an account link, send the account to it, and confirm from a webhook that onboarding finished. By the end the account’s capabilities are enabled and you have not built a form. The flow only asks for what the account’s requirements currently name, so a recipient-only account moves through it in far fewer steps than one that also accepts payments. See Create an account for that choice.

​
Before you start

  • An account. See Create an account.
  • A webhook endpoint with event_source set to connect or all. See Connect events.
  • Two URLs on your site, one to return to and one to refresh from.

​
Steps

1

Create the link

Use type: "onboarding" for a new account, or update to collect more from one that is already live. Both refresh_url and return_url are required.
id identifies the link object itself; the credential that makes the URL work is the opaque token embedded in url’s last path segment, and it is single-use. Do not construct this URL yourself or persist it past its expires_at.
Creating a link invalidates the previous one, reported as previous_link_superseded. Create a link when the account is about to open it, not on every page render, or the link you emailed yesterday stops working.
2

Send the account to the URL

Redirect the account holder to url, or email it to them. The flow asks for whatever is currently due and nothing more.
3

Handle the refresh URL

An expired or already-used link sends the account to refresh_url. Your handler there creates a new link and redirects again:
4

Confirm from the webhook

There is no event that says “the hosted flow finished.” The account lands on return_url when it finishes, abandons halfway, or closes the tab without either, so treat that redirect as a cue to show a status screen, not as confirmation of anything. Confirm from the account’s own events instead.
account.updated
The return redirect is lost entirely if the browser never comes back, since nothing else fires it. Confirm from account.updated and capability.updated, which fire regardless of whether the browser returns.

​
What happens next

An account.updated event with an empty outstanding means nothing is left for the account to provide, not that the account can transact. Wait for capability.updated with status: "active" before you unlock anything. See Monitor onboarding.

​
Errors

Account link endpoints return the standard error envelope.

​
Next steps