How onboarding works

What happens between creating a user and being able to pay them, and how you hear about each step.

Do it: Onboard a user, Embed onboarding · Look it up: Users, User events

From created to payable

A user you create with Create user starts in account_stateonboarding. You should not pay them until they finish signing up in Zay. You send the user to Zay's hosted onboarding — usually by redirecting them to their onboarding_url, or by embedding it in your page. There they verify their phone, confirm their details, and complete identity verification (KYC). When it succeeds, Zay issues their card, and the user activates it — one tap that allows the card to spend from their wallet. The moment the card can spend moves account_state to active and sends user.onboarding_completed, carrying the wallet_address to pay. From then on they can be paid. That moment is the same whether the user finishes in your onboarding link or in the Zay app, and the event is sent once per user.

Linking to a Zay account

Verifying the phone through your onboarding_url is also what links the profile to the person's Zay identity, and so what makes account_state and the wallet address start reflecting their real account. Two consequences worth designing for:

• Someone who already has a Zay wallet still has to open your onboarding_url and verify once. Until they do, their profile stays pending — there is no way to link it from the API.
• The phone number they verify must match the phone_number you created the profile with. If it doesn't, nothing is linked.

Events along the way

Onboarding includes an identity-verification step, so user.kyc_* events arrive before one of the two terminal ones. In flow order:

Event	Meaning
user.onboarding_started	The user started onboarding
user.kyc_submitted	Identity verification was submitted
user.kyc_passed	Identity verification was approved
user.onboarding_completed	The card is issued and can spend — the user can now be paid
user.onboarding_failed	Identity verification was declined for good — the user can never be paid

user.onboarding_completed and user.onboarding_failed are the events to act on. The others are optional progress signals — wire them up if you show onboarding progress to your users.

When a user doesn't finish

A user who stops partway, or whose verification needs another try, sends no event and stays in account_state onboarding — they can still finish. Detect a stalled onboarding by reading account_state with Retrieve user. Only a final refusal sends user.onboarding_failed; the account stays onboarding then too, but will not move again.

Account states

account_state	Meaning
onboarding	Created, not finished signing up
active	Card ready to spend; can be paid
pending_closure	The user asked to close their account; it can still be canceled
closing	The account is being closed
closed	The account is closed