Skip to main content
Onboarding completes an account’s Requirements so its capabilities can go live. There are three ways to do it. They collect the same information.

From the dashboard

You can create an account and onboard it without writing any code.
  1. In the dashboard, open Connect and create an account. Give the person’s email and country, and pick the capabilities they need. Each capability shows how many details it adds.
  2. Open the account’s page and send the person their onboarding link.
  3. Watch the badge on the account’s page. It moves from Waiting for the seller, to Checking, to Live.
If a check fails, the account’s page says why. You can then send a new link from the same page. If you already know some of the person’s details, you can fill them in for them from the account’s page. Only the person can add their payout account.
POST /v1/accounts/{account_id}/account-links · scope connected_accounts:write · full field reference →
type is onboarding for a new account, update to collect more from an existing one, or liveness for the selfie video check alone. 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. A link lasts 30 days.
Creating a link supersedes the previous one of the same type, 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.

The selfie video check

Taking payments needs a selfie video check of the person’s face and ID. See What an account owes. The person does it on their phone, in the hosted flow. It cannot be done through the API. An onboarding or update link asks for it first, before anything else. If the check is all that is left, for example after it failed, send a liveness link instead. It asks for nothing else. liveness_owed on GET /v1/accounts/{account_id} is true when the account needs the check. A liveness link for an account that does not need it gets 400 CONNECTED_ACCOUNT_LIVENESS_NOT_NEEDED. Paying out, holding money and virtual accounts never need the check.

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 uploaded first, then attached. The selfie video check is the one thing you cannot do through the API: send a hosted link for it. 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 goes live when its checks pass. Some are also reviewed by our team, before or after. See How a capability goes live. Subscribe to capability.updated and unlock the account’s features when it arrives. See Monitor onboarding.