Usuários e KYC

Os usuários são os portadores de cartão do seu programa. O usuário precisa de e-mail confirmado, carteira vinculada e KYC aprovado antes de um cartão ser criado.

API v1 · Legado

Esta página faz parte da referência da primeira versão da API da Web3Card, mantida aqui para consulta. A API v1 não recebe integrações novas: a API v2 a substitui, e a plataforma hoje funciona como descrito no resto deste manual.

POST /users

Cria um usuário.

// Request
{
  "email": "[email protected]",
  "walletAddress": "0x71C2a4f3b7c48d19D4a2e9Eb0cE3606eB48a3a4F",
  "chain": "polygon"
}

// Response
{
  "id": "usr_9f4c",
  "email": "[email protected]",
  "emailVerified": false,
  "walletAddress": "0x71C2a4f3b7c48d19D4a2e9Eb0cE3606eB48a3a4F",
  "kycStatus": "not_started",
  "createdAt": "2026-07-19T14:00:00Z"
}

GET /users/{id}

Consulta o perfil do usuário, a situação das verificações e o que está ligado a ele (cofres, cartões).

GET /users

Lista os usuários do seu programa. Aceita os filtros limit, cursor e kycStatus.

KYC

A verificação de identidade passa por um fluxo hospedado, oferecido pelo parceiro de verificação da plataforma. Você nunca lida com documentos de identidade.

POST /users/{id}/kyc/session

Cria uma sessão de verificação e devolve o endereço para redirecionar ou embutir:

// Response
{
  "url": "https://verify.web3card.dev/s/usr_9f4c?vt=abc123",
  "expiresIn": 1800
}

Situações do KYC

Situação	Significado
not_started	Nenhuma sessão criada ainda
pending	Documentos enviados, em análise
approved	Verificação aprovada; cartões podem ser criados
rejected	Verificação recusada; os detalhes vêm no webhook

As mudanças de situação chegam pelos webhooks kyc.approved / kyc.rejected e também aparecem no perfil do usuário.

Confirmação do celular

Alguns países exigem um celular confirmado:

• POST /users/{id}/phone/otp: envia o código por SMS
• POST /users/{id}/phone/verify: confirma o código