Skip to main content

Onboarding Flow

This page describes the end-to-end journey of a cardholder in your program, from signup to first payment. Each step maps to specific API calls, so you can build the entire flow inside your own product.

API v1 · Legacy

This page is part of the reference of the first version of the Web3Card API, kept here for reference. API v1 does not take new integrations: API v2 replaces it, and the platform today works as described in the rest of this manual.

Flow overview​

Signup → Wallet link → KYC → Vault deployment → Card creation → Top-up → First payment

1. Signup​

Create the user with their email. The email is verified with a one-time code delivered by the platform.

  • POST /users: create the user
  • POST /users/{id}/email/verify: confirm the OTP code

The user proves ownership of their wallet by signing a message (Sign-In with Ethereum). The wallet becomes the user's authentication identity and the owner of their vault.

  • POST /auth/nonce: generate the message to sign
  • POST /auth/verify: verify the SIWE signature

3. KYC​

Identity verification is required by the card network and the issuer. Web3Card provides a hosted verification flow you can embed or redirect to.

  • POST /users/{id}/kyc/session: start a verification session
  • Webhook kyc.approved or kyc.rejected: result notification

4. Vault deployment​

With KYC approved, deploy the user's individual multisig vault on their chosen chain. The user's wallet is registered as owner; the settlement operator is added as a co-signer for authorized card settlements only.

  • POST /vaults: deploy the vault
  • GET /vaults/{id}: check deployment status

5. Card creation​

Create a virtual card instantly, or start a physical card order for worldwide delivery.

  • POST /cards: create a virtual card
  • POST /card-orders: order a physical card

6. Top-up​

The user funds the vault by transferring USDC, USDT, or your project token to the vault address on the selected chain. Balance updates are pushed via webhook.

7. First payment​

The card is live. Payments are authorized in real time against the vault balance, and every transaction is available through the API and webhooks.

For details on each stage, see the Guides section.

Last updated on