Início rápido

Este início rápido leva você do zero ao primeiro cartão virtual em cinco passos. Ele parte do princípio de que você já tem as credenciais de parceiro; se ainda não tem, escreva para [email protected] para montar o seu programa.

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.

1. Pegue a sua chave de API

Toda chamada à API de parceiros é autenticada com a sua chave de API no cabeçalho Authorization:

curl https://api.web3card.dev/v1/ping \
  -H "Authorization: Bearer w3c_live_xxxxxxxxxxxxxxxx"

As chaves de sandbox começam com w3c_test_ e trabalham com cofres em testnet. No modo sandbox nenhum dinheiro de verdade se move.

2. Crie um usuário

Os usuários são os portadores de cartão do seu programa. Crie um com o endereço da carteira e o e-mail dele:

curl -X POST https://api.web3card.dev/v1/users \
  -H "Authorization: Bearer w3c_test_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "walletAddress": "0x71C2a4f3b7c48d19D4a2e9Eb0cE3606eB48a3a4F",
    "chain": "polygon"
  }'

3. Faça o KYC

O portador precisa passar pela verificação de identidade antes de o cartão ser ativado. Peça o link de uma sessão de KYC e mande o usuário para ele:

curl -X POST https://api.web3card.dev/v1/users/usr_9f4c/kyc/session \
  -H "Authorization: Bearer w3c_test_xxxxxxxxxxxxxxxx"

Quando a verificação termina, chega o webhook kyc.approved. Veja Usuários e KYC.

4. Implante o cofre do usuário

Cada cartão tem por trás o seu próprio cofre multisig em contrato inteligente. Implante o cofre na rede do usuário:

curl -X POST https://api.web3card.dev/v1/vaults \
  -H "Authorization: Bearer w3c_test_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "userId": "usr_9f4c", "chain": "polygon", "currency": "USDC" }'

5. Crie um cartão virtual

curl -X POST https://api.web3card.dev/v1/cards \
  -H "Authorization: Bearer w3c_test_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "userId": "usr_9f4c", "type": "virtual" }'

A resposta traz o id do cartão e a situação dele:

{
  "id": "card_3b7c",
  "userId": "usr_9f4c",
  "type": "virtual",
  "status": "active",
  "last4": "1234",
  "network": "visa",
  "createdAt": "2026-07-19T14:00:00Z"
}

Com saldo no cofre, o cartão está pronto para gastar. Siga para o guia de recargas ou assine os webhooks para receber os eventos na hora.