# Documentação Web3Card
> Infraestrutura white-label de cartões cripto para projetos web3. Cartões Visa recarregados com stablecoins, com a sua marca e o seu domínio.
---
Source: https://docs.web3card.dev/pt-BR/
# Lance o seu programa de cartões com a sua própria marca
O manual da Web3Card, o software white-label para cartões Visa recarregados com stablecoins. Do primeiro cadastro até a API.
A Web3Card é um software white-label para programas de cartões. A sua empresa opera um programa de cartões Visa recarregados com stablecoins, com a sua marca no app e o seu domínio na barra de endereço. Os seus usuários criam a conta e cuidam dos cartões em um app com a cara da sua empresa.
Esta documentação é o manual de uso da plataforma. Ela segue o caminho de uma empresa nova, do primeiro acesso ao uso avançado da API, e cresce junto com o produto. Cada capítulo é publicado quando a função que ele descreve fica pronta.
**Em que ponto este manual está**
A versão 2 da Web3Card está abrindo por etapas, e este manual cresce junto. A criação de conta e o login estão terminados nos dois painéis e estão documentados aqui por inteiro. Os próximos capítulos (identidade, carteiras, cartões, marca, domínio próprio e a referência da API) estão listados em [Do cadastro ao lançamento](https://docs.web3card.dev/pt-BR/platform/path-to-launch/) e são publicados conforme cada parte termina.
## O que é a Web3Card
A Web3Card é uma provedora de tecnologia. Ela entrega três coisas:
- **Software.** Um painel para a sua empresa e um app para os seus usuários, os dois prontos para levar a sua marca.
- **Infraestrutura.** Hospedagem, segurança, acesso às contas e a ligação com as redes de cartão por meio de instituições parceiras.
- **Integração.** Uma API para operar o seu programa de cartões a partir dos seus próprios sistemas.
A Web3Card não é banco nem instituição financeira. Os cartões são emitidos por instituições parceiras, licenciadas e reguladas, dentro da rede Visa.
## Dois painéis, uma plataforma
A plataforma tem dois lados. Cada um tem o seu endereço, as suas contas e o seu público.
| | Business | Pessoal |
| --- | --- | --- |
| Quem usa | A empresa que opera o programa de cartões e a equipe dela | O usuário final de cada empresa |
| Para que serve | Configurar e operar o programa | Criar a conta e usar o cartão |
| Endereço | `business.web3card.dev`, o mesmo para todas as empresas | O domínio da própria empresa, como `cartoes.suaempresa.com` |
| Marca na tela | Web3Card | A marca da empresa |
Leia [Como a plataforma funciona](https://docs.web3card.dev/pt-BR/platform/overview/) para ver o quadro completo.
## Como esta documentação está organizada
| Capítulo | O que cobre | Situação |
| --- | --- | --- |
| [A plataforma](https://docs.web3card.dev/pt-BR/platform/overview/) | Os dois painéis, o que é white-label e o caminho do cadastro ao lançamento | Publicado |
| [Playground de cartões](https://docs.web3card.dev/pt-BR/playground/) | Desenhe um cartão de exemplo em 3D, veja o que cada ação faz e veja a prévia do app dos seus usuários | Prévia de telas em desenvolvimento |
| [Construtor de fluxos](https://docs.web3card.dev/pt-BR/flow-builder/) | Escolha um token numa rede e veja a rota dele até a sua carteira, o contrato do seu programa ou um cartão Visa, com as chamadas de API de cada passo | Ilustrativo: a API v2 está planejada |
| [Cartões](https://docs.web3card.dev/pt-BR/cards/countries/) | Os países e regiões onde os cartões não funcionam, e onde podem ser usados com o Apple Pay | Publicado |
| [Acesso à conta](https://docs.web3card.dev/pt-BR/access/create-business-account/) | Criar a conta, entrar e sair, trocar a senha, trocar o autenticador, regras de segurança e mensagens | Publicado |
| [API](https://docs.web3card.dev/pt-BR/api/overview/) | O que é a API v2 e como ela foi desenhada. A [referência da API v1](https://docs.web3card.dev/pt-BR/api-reference/overview/), com exemplos de código, fica como legado | v2: visão geral publicada, referência planejada. v1: legado |
| Identidade, carteiras, cartões, marca, domínio, equipe | Os próximos passos do caminho | A caminho. Veja [Do cadastro ao lançamento](https://docs.web3card.dev/pt-BR/platform/path-to-launch/) |
Não conhece algum termo? O [glossário](https://docs.web3card.dev/pt-BR/glossary/) explica cada um em uma frase.
## Idiomas
Esta documentação está disponível em inglês e em português do Brasil. Use o menu de idiomas no topo da página para trocar. As telas da plataforma estão em inglês, por isso os nomes de botões e de campos aparecem em inglês nas duas versões.
## Para assistentes de IA
O texto completo desta documentação também é publicado em texto puro, pronto para ser lido por modelos de linguagem:
- [llms.txt](https://docs.web3card.dev/pt-BR/llms.txt): o índice das páginas, com o resumo de cada uma em uma linha
- [llms-full.txt](https://docs.web3card.dev/pt-BR/llms-full.txt): todas as páginas em um arquivo só
## Precisa de ajuda?
Escreva para [contact@web3card.dev](mailto:contact@web3card.dev) ou visite [web3card.dev](https://web3card.dev).
---
Source: https://docs.web3card.dev/pt-BR/playground/
## O que dá para testar aqui
**Em desenvolvimento**
O Card setup e o White label, as duas telas do painel Business em que este playground se baseia, estão sendo construídos. As opções e os textos podem mudar.
O playground roda no seu navegador. Nada é enviado, e um logo que você escolher fica só nesta página. O cartão é um exemplo, com dados de exemplo.
### Desenhe o seu cartão
O **Card setup**, no painel Business, é onde a sua empresa escolhe os cartões que os usuários podem ter e a cara de cada um. O playground traz as opções de um cartão desenhado pela empresa: um material pronto, a cor, a textura, o acabamento, o granulado, a cor das marcas e a sua marca ou o seu logo.
O nome no cartão é sempre o nome verificado do usuário. A marca da bandeira é posta pela plataforma e não pode ser movida.
### Ações do cartão
Cada ação mostra no cartão o que ela faz.
| Ação | O que faz | Onde |
| --- | --- | --- |
| Criar cartão | Cria um cartão virtual para um usuário com a identidade verificada, pago com o saldo do programa no seu contrato | Painel Business e app dos usuários |
| Recarregar | Leva saldo do programa para um cartão. A taxa de recarga é paga por cima, então o cartão recebe o valor inteiro | Painel Business e app dos usuários |
| Congelar | Bloqueia o cartão com um clique. Descongelar pede o código do aplicativo autenticador | Painel Business e app dos usuários |
| Ver dados | Mostra o número completo, a validade e o código de segurança, depois do código do aplicativo autenticador. Eles não ficam guardados em lugar nenhum | App dos usuários |
| Cobrança | O nome no cartão e o endereço de cobrança, que uma loja on-line pede no pagamento | Painel Business e app dos usuários |
| Limites | Um limite mensal por cartão, e uma faixa para a primeira carga e para as recargas por tipo de cartão | Painel Business e app dos usuários |
| Renomear | Muda o apelido do cartão. O nome impresso no cartão não muda | Painel Business |
| Cancelar | Encerra o cartão de vez | Painel Business |
### O app dos seus usuários
O **White label**, no painel Business, é onde a sua empresa define o nome, o logo e as cores do app que os usuários veem. A prévia mostra a sua marca em cada um dos quatro temas da plataforma, com a sua cor de destaque.
### Medidas
O cartão segue o tamanho ID-1 dos cartões de pagamento: 85,60 × 53,98 mm, com cantos arredondados de 3,18 mm. Ligue **Medidas** acima do cartão para vê-las.
---
Source: https://docs.web3card.dev/pt-BR/flow-builder/
## O que o construtor de fluxos mostra
**Ilustrativo**
O construtor de fluxos mostra como um token chega a um cartão do seu programa, e as chamadas que queremos que a API v2 tenha em cada passo. A API v2 está planejada: nenhum endereço foi publicado ainda, e os nomes, os campos e as respostas podem mudar. A Bridge no app dos seus usuários está sendo construída.
O construtor de fluxos roda no seu navegador. Nada é enviado e nenhuma carteira é conectada. Os valores, os endereços e os identificadores do código são exemplos.
Escolha um token e a rede dele à esquerda, depois onde ele deve terminar. O fluxo à direita desenha cada passo por que o token passa. Passe o mouse num passo para ver a chamada dele no código abaixo, ou clique para ir até ela.
### Onde um fluxo começa
Um fluxo começa na carteira do próprio usuário, numa destas redes.
| Rede | Tokens |
| --- | --- |
| BNB Chain | BNB, USDT, USDC |
| Ethereum | ETH, USDT, USDC |
| Arbitrum | ETH, USDT, USDC |
| Polygon | POL, USDT, USDC |
| Base | ETH, USDC |
**O token do seu projeto** mostra como um token do seu próprio projeto pode entrar no mesmo fluxo: primeiro ele é trocado numa exchange descentralizada (DEX) da rede dele, depois segue a mesma rota de qualquer outro token. Isso só funciona para um token que tenha mercado numa DEX da rede dele.
### Onde um fluxo termina
| Destino | O que acontece |
| --- | --- |
| **A sua carteira** | O usuário recebe o token do programa, na BNB Chain, na própria carteira |
| **Contrato do programa** | O token do programa é depositado no contrato do seu programa e vira saldo do programa |
| **Cartão Visa** | Depois do depósito, o saldo vai do programa para um cartão do usuário, pronto para usar |
O **token do programa** é o token com que o contrato do seu programa trabalha: USDT ou USDC, na BNB Chain.
### Os passos de uma rota
| Passo | O que faz |
| --- | --- |
| **Troca em DEX** | Converte o token no token do programa, na mesma rede |
| **Web3Card Bridge** | Traz o token de outra rede para a BNB Chain, convertendo no caminho quando precisa |
| **Depósito** | Leva o token do programa da carteira do usuário para o contrato do seu programa |
| **Recarga** | Leva saldo do programa para um cartão. A taxa de recarga é paga por cima, então o cartão recebe o valor inteiro |
O usuário assina cada transação na própria carteira. Os tokens saem da carteira do usuário e chegam na mesma carteira: nada passa por você nem pela plataforma no caminho. Um token que já é o token do programa na BNB Chain pula a troca e a ponte.
### As chamadas
Cada passo do fluxo tem uma chamada no painel **Código**, em cURL e em JavaScript, com uma resposta de exemplo. Elas seguem os [princípios da API v2](https://docs.web3card.dev/pt-BR/api/overview/): operações que você acompanha até terminarem, uma chave que deixa repetir um pedido sem risco, e eventos assinados.
| Chamada | O que faz |
| --- | --- |
| Pedir uma rota | Devolve a rota até o token do programa e as transações para o usuário assinar |
| Acompanhar a transferência | Lê a operação da transferência até ela terminar |
| Depositar no programa | Devolve as duas transações de um depósito: a autorização do valor exato e o depósito |
| Recarregar o cartão | Leva saldo do programa para um cartão. Leva uma chave de idempotência |
| Receber o evento | Os seus sistemas recebem um evento assinado quando o fluxo termina |
`$W3C_API` é o endereço da API, que ainda não foi publicado, e `$W3C_API_KEY` é a sua chave.
## Páginas relacionadas
| Página | O que traz |
| --- | --- |
| [Playground de cartões](https://docs.web3card.dev/pt-BR/playground/) | Desenhe um cartão de exemplo e veja o que cada ação faz |
| [Visão geral da API v2](https://docs.web3card.dev/pt-BR/api/overview/) | O que é a API v2 e os princípios em que ela é desenhada |
| [Cartões: países](https://docs.web3card.dev/pt-BR/cards/countries/) | Onde os cartões não funcionam, e onde podem ser usados com Apple Pay |
---
Source: https://docs.web3card.dev/pt-BR/platform/overview/
# Como a plataforma funciona
A Web3Card tem dois lados que trabalham juntos. A empresa opera o seu programa de cartões no painel **Business**. Os usuários dessa empresa criam a conta e usam os cartões no app **Pessoal**, que leva a marca da empresa.
## O painel Business
O painel Business é da empresa que opera o programa de cartões e da equipe dela.
- **Um endereço para todos.** Toda empresa usa o mesmo endereço: `business.web3card.dev`.
- **A empresa vem da conta.** Não há nada para escolher na tela de login. A plataforma sabe a qual empresa você pertence pela conta com que você entra.
- **Dois papéis.** Quem cria a empresa é o **dono** dela. As outras pessoas vão entrar na equipe por convite do dono, como **membros**.
- **A marca Web3Card aparece.** A empresa que compra o software sabe que compra da Web3Card, então o painel não esconde isso.
## O app Pessoal
O app Pessoal é do usuário final: a pessoa que tem o cartão.
- **Um endereço por empresa.** O app fica no domínio da própria empresa, como `cartoes.suaempresa.com`. A barra de endereço mostra esse domínio o tempo todo.
- **A empresa vem do domínio.** Quando o usuário abre o endereço, a plataforma reconhece de qual empresa é aquele domínio e carrega o nome, o logo e o tema dela.
- **A marca Web3Card não aparece.** O usuário vê a marca da empresa, na tela e nas mensagens que a plataforma envia.
A Web3Card usa a própria plataforma como qualquer outra empresa. O app Pessoal dela fica em `wallet.web3card.app`.
## Lado a lado
| | Business | Pessoal |
| --- | --- | --- |
| Quem entra | O dono e a equipe de uma empresa | Os usuários finais dessa empresa |
| Endereço | `business.web3card.dev` | O domínio da empresa |
| Como a empresa é identificada | Pela conta que está logada | Pelo domínio na barra de endereço |
| Marca na tela | Web3Card | A marca da empresa |
| Um mesmo e-mail pode ter | Uma conta no painel inteiro | Uma conta no app de cada empresa |
## As contas são separadas
Uma conta Business e uma conta Pessoal são contas diferentes, mesmo quando usam o mesmo e-mail.
- No painel **Business**, cada e-mail tem uma conta. Essa conta pertence a uma empresa.
- No app **Pessoal**, cada e-mail tem uma conta por empresa. A mesma pessoa pode ser usuária de duas empresas diferentes. São duas contas independentes, cada uma com a sua senha e o seu autenticador.
A mesma regra vale para o celular: um número pode ser usado uma vez no painel Business e uma vez no app de cada empresa.
## Quem faz o quê
| | Responsabilidade |
| --- | --- |
| **A sua empresa** | É dona da marca, do domínio e da relação com os usuários. Decide como o programa é apresentado e operado. |
| **A Web3Card** | Fornece o software, a infraestrutura e a API. A Web3Card é uma provedora de tecnologia, não é banco nem instituição financeira. |
| **As instituições parceiras** | Instituições licenciadas e reguladas, dentro da rede Visa. São elas que emitem os cartões. |
## O que este manual cobre hoje
O acesso à conta está terminado nos dois painéis e documentado passo a passo:
- [criar uma conta Business](https://docs.web3card.dev/pt-BR/access/create-business-account/) e [criar uma conta Pessoal](https://docs.web3card.dev/pt-BR/access/create-personal-account/), cada uma com três etapas de verificação
- [entrar e sair](https://docs.web3card.dev/pt-BR/access/sign-in/), com senha e código do autenticador
- [trocar uma senha esquecida](https://docs.web3card.dev/pt-BR/access/reset-password/)
- [trocar o autenticador](https://docs.web3card.dev/pt-BR/access/replace-authenticator/) quando o celular é perdido
- o app Pessoal abrindo com a marca da empresa dona do domínio
Tudo o que vem depois do login está em construção. A ordem está em [Do cadastro ao lançamento](https://docs.web3card.dev/pt-BR/platform/path-to-launch/).
---
Source: https://docs.web3card.dev/pt-BR/platform/white-label/
# White-label: a sua marca, o seu domínio
Na Web3Card, white-label quer dizer que os seus usuários lidam com a sua marca do começo ao fim. Eles abrem o seu domínio, veem o seu nome e o seu logo e recebem mensagens assinadas pela sua empresa.
## O que os seus usuários veem
| Onde | O que aparece |
| --- | --- |
| Barra de endereço | O seu domínio, como `cartoes.suaempresa.com`, em todas as telas |
| Aba do navegador | O seu nome e o seu logo |
| Telas | O seu nome, o seu logo e o tema que você escolheu |
| Aplicativo autenticador | O seu nome ao lado do e-mail do usuário |
| Códigos por e-mail e por SMS | O seu nome, como remetente e no texto |
O app Pessoal é o mesmo software para todas as empresas. O que faz dele o seu app é configuração, não código sob medida:
- **Nome.** Aparece nas telas, na aba do navegador e nas mensagens.
- **Logo.** Uma imagem quadrada. Aparece pequeno, ao lado do seu nome, e vira o ícone da aba do navegador. Sem logo, o app mostra a inicial do seu nome.
- **Tema.** Um entre quatro: **Graphite Dark**, **Graphite Light**, **Gold Dark** e **Ivory**. É o padrão para os seus usuários.
**Situação: planejado**
Hoje a marca de cada empresa é configurada pela equipe da Web3Card. As telas em que o dono edita nome, logo e tema no painel Business estão planejadas. Esta página vai ganhar o passo a passo quando elas abrirem.
## Cada pessoa pode escolher outro tema
O tema que você escolhe é o ponto de partida. Cada pessoa pode trocar para qualquer um dos quatro no próprio aparelho.
- **App Pessoal.** No pé do menu, **Theme** mostra o nome do tema atual. A tela **Account** tem a mesma escolha em **Appearance**.
- **Painel Business.** No pé do menu lateral, **Theme**.
A escolha fica guardada só naquele navegador. Em outro aparelho a pessoa vê de novo o padrão da empresa.
## O seu domínio
O padrão é o app Pessoal rodar em um domínio que é seu.
**Use um subdomínio.** Endereços como `app.suaempresa.com` ou `cartoes.suaempresa.com` funcionam em qualquer provedor de DNS. O domínio puro (`suaempresa.com`) não funciona em todos, e o `www` costuma ser o seu site institucional.
**Como funciona:**
1. Você escolhe o subdomínio.
2. Você cria um registro no seu DNS: um CNAME que aponta o subdomínio para a plataforma. O valor exato aparece no seu painel Business.
3. A plataforma emite o certificado HTTPS do seu domínio e renova sozinha.
4. Os seus usuários abrem o seu endereço. A plataforma reconhece o domínio e carrega a sua marca.
Não é um redirecionamento. A barra de endereço continua mostrando o seu domínio em todas as telas. Só você mexe no seu DNS: a Web3Card nunca pede acesso a ele.
Um endereço que não está ligado a nenhuma empresa mostra uma página neutra, **This address is not active**, sem marca nenhuma.
**Situação: planejado**
Ligar um domínio pelo painel Business está planejado. O passo a passo, com o registro a criar e como conferir que ele está ativo, será publicado aqui quando abrir.
## O que o white-label cobre
White-label quer dizer que os seus usuários veem a sua marca e o seu domínio, e não os nossos. Vale para tudo o que o usuário enxerga ao usar o app: o endereço, as telas e as mensagens.
Não é uma promessa de que a tecnologia por trás do seu programa nunca poderá ser identificada por quem investigar a infraestrutura. Se isso importa para o seu negócio, fale com a gente antes do lançamento.
## As etapas de uma empresa
A empresa não recebe tudo no primeiro dia. A conta avança por etapas, e cada etapa libera mais da plataforma.
| Etapa | O que ela libera |
| --- | --- |
| **Primeira etapa** | Você criou a conta e pode conhecer o painel Business. Nada ali é real ainda. |
| **Próximas etapas** | Um cartão de teste para o dono e depois a ativação completa: marca, domínio próprio, equipe e usuários. |
A tela Home do painel Business mostra um aviso que diz em que etapa a sua empresa está.
**Situação: em desenvolvimento**
As telas do painel estão sendo redesenhadas, e os requisitos das próximas etapas ainda estão sendo definidos. As duas coisas serão documentadas aqui antes de abrirem.
---
Source: https://docs.web3card.dev/pt-BR/platform/path-to-launch/
# Do cadastro ao lançamento
Esta página mostra o caminho inteiro de uma empresa na Web3Card, na ordem em que acontece. Cada passo ganha o link do seu guia assim que o guia existe. Ela também é o mapa desta documentação: todo capítulo que ainda vai chegar está listado aqui.
## Situação de cada passo
| Situação | Significado |
| --- | --- |
| **Pronto** | As telas estão terminadas e o guia está publicado. |
| **Em desenvolvimento** | Está sendo construído agora. O guia é publicado quando a função terminar. |
| **Planejado** | É o próximo da fila. Os detalhes ainda podem mudar. |
## O caminho da sua empresa
A ordem é fixa. Cada passo abre quando o anterior termina.
| # | Passo | Onde | Situação |
| --- | --- | --- | --- |
| 1 | [Criar a conta da empresa](https://docs.web3card.dev/pt-BR/access/create-business-account/): e-mail, aplicativo autenticador e celular | Business | Pronto |
| 2 | Inscrição: a taxa única de inscrição do software, paga com cartão | Business | Em desenvolvimento |
| 3 | Verificar a identidade do dono | Business | Em desenvolvimento |
| 4 | Verificar a empresa | Business | Em desenvolvimento |
| 5 | Criar o contrato do seu programa: a rede e o token são escolhidos uma vez | Business | Em desenvolvimento |
| 6 | Fazer o primeiro depósito | Business | Em desenvolvimento |
| 7 | Card setup: os cartões que os seus usuários podem ter e a cara de cada um. Teste no [playground de cartões](https://docs.web3card.dev/pt-BR/playground/) | Business | Em desenvolvimento |
| 8 | White label: o nome, o logo e as cores do app que os seus usuários veem | Business | Em desenvolvimento |
| 9 | [Ligar o seu domínio](https://docs.web3card.dev/pt-BR/platform/white-label/#your-own-domain) | Business | Planejado |
| 10 | Convidar a equipe | Business | Em desenvolvimento |
| 11 | Operar o programa a partir dos seus sistemas com a [API](https://docs.web3card.dev/pt-BR/api/overview/) | API | Planejado |
Planos e preços estão em [web3card.dev](https://web3card.dev/#pricing).
## O sandbox
Depois das duas verificações, **Go to sandbox**, no fim do menu do painel Business, abre um segundo painel com bancos de teste e dinheiro de teste, para treinar antes de ir para a produção. Ele abre já com a conta conectada, e nada nele é de verdade.
**Em desenvolvimento**
O sandbox está sendo construído junto com os passos acima.
## O caminho dos seus usuários
Os seus usuários seguem um caminho mais curto, dentro do app que leva a sua marca. O app da sua empresa abre para eles depois que o seu programa está ativo.
| # | Passo | Situação |
| --- | --- | --- |
| 1 | [Criar a conta](https://docs.web3card.dev/pt-BR/access/create-personal-account/): e-mail, aplicativo autenticador e celular | Pronto |
| 2 | [Entrar](https://docs.web3card.dev/pt-BR/access/sign-in/) com senha e código do autenticador | Pronto |
| 3 | Vincular a carteira | Em desenvolvimento |
| 4 | Fazer o primeiro depósito | Em desenvolvimento |
| 5 | Verificar a identidade (KYC) | Em desenvolvimento |
| 6 | Pedir o cartão | Em desenvolvimento |
| 7 | Recarregar o cartão, depositar e sacar | Em desenvolvimento |
## O que já está documentado
| Guia | Vale para |
| --- | --- |
| [Criar uma conta Business](https://docs.web3card.dev/pt-BR/access/create-business-account/) | Business |
| [Criar uma conta Pessoal](https://docs.web3card.dev/pt-BR/access/create-personal-account/) | Pessoal |
| [Entrar e sair](https://docs.web3card.dev/pt-BR/access/sign-in/) | Os dois |
| [Trocar a senha](https://docs.web3card.dev/pt-BR/access/reset-password/) | Os dois |
| [Perdeu o celular: trocar o autenticador](https://docs.web3card.dev/pt-BR/access/replace-authenticator/) | Os dois |
| [Regras de segurança e limites](https://docs.web3card.dev/pt-BR/access/security-and-limits/) | Os dois |
| [Playground de cartões](https://docs.web3card.dev/pt-BR/playground/) | Uma prévia do Card setup e do White label |
Esta página é atualizada sempre que um passo muda de situação.
---
Source: https://docs.web3card.dev/pt-BR/cards/countries/
# Países e regiões
Os cartões seguem as sanções internacionais e as regras das instituições parceiras que os emitem. Esta página lista os países e regiões onde os cartões não funcionam, e onde eles podem ser usados com o Apple Pay.
**A lista pode mudar**
Ela acompanha as sanções internacionais e as instituições parceiras que emitem os cartões, e é atualizada quando elas mudam. Um programa de cartões pode ter mais restrições do que as listadas aqui. Atualizada em outubro de 2026.
## Disponibilidade por programa de cartões
A Web3Card se liga a mais de um programa de cartões. As listas desta página são as do programa principal, o **SU**. Outros programas, oferecidos a alguns usuários, têm restrições próprias: um país bloqueado no programa principal pode estar aberto em outro, e um país onde os cartões funcionam pode ter uma exigência específica em algum programa. Nesta página esses programas aparecem pela sigla: **MO**, **UN-B** e **UN-Z**.
A bolinha ao lado de um país mostra o nível dele. Pare o mouse ou toque na bolinha para ver o que cada programa diz do país.
- **Atenção**: Os cartões funcionam, com uma exigência específica em alguns programas.
- **Parcial**: Bloqueado no programa principal; alguns programas não o restringem.
- **Restrito**: Bloqueado em todos os programas.
O programa que um usuário pode ter depende da empresa e do usuário. Os níveis são uma orientação, não a promessa de que um cartão está disponível.
## Onde os cartões não funcionam
Os cartões não funcionam nestes 29 países no programa principal:
Afeganistão (Parcial: SU bloqueado; MO bloqueado; UN-B bloqueado; UN-Z sem restrição), Belarus (Restrito: SU bloqueado; MO bloqueado; UN-B bloqueado; UN-Z bloqueado), Burundi (Parcial: SU bloqueado; MO sem restrição; UN-B sem restrição; UN-Z sem restrição), República Centro-Africana (Parcial: SU bloqueado; MO bloqueado; UN-B só cartão virtual, sem entrega de cartão físico; UN-Z só cartão virtual, sem entrega de cartão físico), China continental (Parcial: SU bloqueado; MO sem restrição; UN-B sem restrição; UN-Z sem restrição), Costa do Marfim (Parcial: SU bloqueado; MO sem restrição; UN-B sem restrição; UN-Z sem restrição), Cuba (Restrito: SU bloqueado; MO bloqueado; UN-B bloqueado; UN-Z bloqueado), República Democrática do Congo (Parcial: SU bloqueado; MO bloqueado; UN-B sem restrição; UN-Z sem restrição), Eritreia (Parcial: SU bloqueado; MO sem restrição; UN-B sem restrição; UN-Z sem restrição), Guiné (Parcial: SU bloqueado; MO sem restrição; UN-B sem restrição; UN-Z sem restrição), Guiné-Bissau (Parcial: SU bloqueado; MO sem restrição; UN-B sem restrição; UN-Z sem restrição), Haiti (Parcial: SU bloqueado; MO bloqueado; UN-B sem restrição; UN-Z sem restrição), Irã (Restrito: SU bloqueado; MO bloqueado; UN-B bloqueado; UN-Z bloqueado), Iraque (Parcial: SU bloqueado; MO bloqueado; UN-B bloqueado; UN-Z sem restrição), Líbano (Parcial: SU bloqueado; MO bloqueado; UN-B sem restrição; UN-Z sem restrição), Líbia (Restrito: SU bloqueado; MO bloqueado; UN-B bloqueado; UN-Z bloqueado), Mali (Parcial: SU bloqueado; MO bloqueado; UN-B sem restrição; UN-Z sem restrição), Mianmar (Restrito: SU bloqueado; MO bloqueado; UN-B bloqueado; UN-Z bloqueado), Nicarágua (Parcial: SU bloqueado; MO bloqueado; UN-B sem restrição; UN-Z sem restrição), Coreia do Norte (Restrito: SU bloqueado; MO bloqueado; UN-B bloqueado; UN-Z bloqueado), Rússia (Restrito: SU bloqueado; MO bloqueado; UN-B bloqueado; UN-Z bloqueado), Somália (Restrito: SU bloqueado; MO bloqueado; UN-B bloqueado; UN-Z bloqueado), Sudão do Sul (Parcial: SU bloqueado; MO bloqueado; UN-B só cartão virtual, sem entrega de cartão físico; UN-Z só cartão virtual, sem entrega de cartão físico), Sudão (Parcial: SU bloqueado; MO sem restrição; UN-B bloqueado; UN-Z bloqueado), Síria (Restrito: SU bloqueado; MO bloqueado; UN-B bloqueado; UN-Z bloqueado), Ucrânia (Parcial: SU bloqueado; MO sem restrição; UN-B bloqueado; UN-Z bloqueado), Venezuela (Restrito: SU bloqueado; MO bloqueado; UN-B bloqueado; UN-Z bloqueado), Iêmen (Parcial: SU bloqueado; MO bloqueado; UN-B sem restrição; UN-Z sem restrição), Zimbábue (Restrito: SU bloqueado; MO bloqueado; UN-B bloqueado; UN-Z bloqueado).
### Regiões
Também não funcionam nestas regiões:
Ambazônia (Parcial: SU bloqueado; MO sem restrição; UN-B sem restrição; UN-Z sem restrição), Kosovo (Parcial: SU bloqueado; MO sem restrição; UN-B sem restrição; UN-Z sem restrição), Chipre do Norte (Parcial: SU bloqueado; MO sem restrição; UN-B sem restrição; UN-Z sem restrição), Territórios ocupados da Geórgia (Parcial: SU bloqueado; MO sem restrição; UN-B sem restrição; UN-Z sem restrição), Transnístria (Parcial: SU bloqueado; MO sem restrição; UN-B sem restrição; UN-Z sem restrição), Saara Ocidental (Parcial: SU bloqueado; MO sem restrição; UN-B sem restrição; UN-Z sem restrição).
## Apple Pay
Onde o cartão puder ser adicionado ao Apple Pay, o Apple Pay só funciona nos países e regiões em que a Apple o oferece, e nunca nos lugares listados acima. A Apple mantém a lista na página [Countries and regions that support Apple Pay](https://support.apple.com/en-my/102775), publicada em 19 de outubro de 2026.
Estes são os países da lista da Apple onde os cartões funcionam:
- África: Egito, Maurício, Marrocos, África do Sul.
- Ásia-Pacífico: Austrália, Hong Kong, Japão, Macau, Malásia, Mongólia, Nova Zelândia, Filipinas, Singapura, Coreia do Sul, Taiwan, Vietnã.
- Europa: Albânia, Andorra, Armênia, Áustria (Atenção: SU sem restrição; MO sem restrição; UN-B sem restrição; UN-Z documento de identidade emitido aqui não é aceito), Azerbaijão, Bélgica (Atenção: SU sem restrição; MO sem restrição; UN-B sem restrição; UN-Z documento de identidade emitido aqui não é aceito), Bósnia e Herzegovina, Bulgária (Atenção: SU sem restrição; MO sem restrição; UN-B sem restrição; UN-Z documento de identidade emitido aqui não é aceito), Croácia (Atenção: SU sem restrição; MO sem restrição; UN-B sem restrição; UN-Z documento de identidade emitido aqui não é aceito), Chipre (Atenção: SU sem restrição; MO sem restrição; UN-B sem restrição; UN-Z documento de identidade emitido aqui não é aceito), Tchéquia (Atenção: SU sem restrição; MO sem restrição; UN-B sem restrição; UN-Z documento de identidade emitido aqui não é aceito), Dinamarca (Atenção: SU sem restrição; MO sem restrição; UN-B sem restrição; UN-Z documento de identidade emitido aqui não é aceito), Estônia (Atenção: SU sem restrição; MO sem restrição; UN-B sem restrição; UN-Z documento de identidade emitido aqui não é aceito), Ilhas Faroé, Finlândia (Atenção: SU sem restrição; MO sem restrição; UN-B sem restrição; UN-Z documento de identidade emitido aqui não é aceito), França (Atenção: SU sem restrição; MO sem restrição; UN-B sem restrição; UN-Z documento de identidade emitido aqui não é aceito), Geórgia, Alemanha (Atenção: SU sem restrição; MO sem restrição; UN-B sem restrição; UN-Z documento de identidade emitido aqui não é aceito), Grécia (Atenção: SU sem restrição; MO sem restrição; UN-B sem restrição; UN-Z documento de identidade emitido aqui não é aceito), Groenlândia, Guernsey, Hungria (Atenção: SU sem restrição; MO sem restrição; UN-B sem restrição; UN-Z documento de identidade emitido aqui não é aceito), Islândia (Atenção: SU sem restrição; MO sem restrição; UN-B sem restrição; UN-Z documento de identidade emitido aqui não é aceito), Irlanda (Atenção: SU sem restrição; MO sem restrição; UN-B sem restrição; UN-Z documento de identidade emitido aqui não é aceito), Ilha de Man, Itália (Atenção: SU sem restrição; MO sem restrição; UN-B sem restrição; UN-Z documento de identidade emitido aqui não é aceito), Jersey, Cazaquistão, Quirguistão, Letônia (Atenção: SU sem restrição; MO sem restrição; UN-B sem restrição; UN-Z documento de identidade emitido aqui não é aceito), Liechtenstein (Atenção: SU sem restrição; MO sem restrição; UN-B sem restrição; UN-Z documento de identidade emitido aqui não é aceito), Lituânia (Atenção: SU sem restrição; MO sem restrição; UN-B sem restrição; UN-Z documento de identidade emitido aqui não é aceito), Luxemburgo (Atenção: SU sem restrição; MO sem restrição; UN-B sem restrição; UN-Z documento de identidade emitido aqui não é aceito), Malta (Atenção: SU sem restrição; MO sem restrição; UN-B sem restrição; UN-Z documento de identidade emitido aqui não é aceito), Moldávia, Mônaco, Montenegro, Países Baixos (Atenção: SU sem restrição; MO sem restrição; UN-B sem restrição; UN-Z documento de identidade emitido aqui não é aceito), Macedônia do Norte, Noruega (Atenção: SU sem restrição; MO sem restrição; UN-B sem restrição; UN-Z documento de identidade emitido aqui não é aceito), Polônia (Atenção: SU sem restrição; MO sem restrição; UN-B sem restrição; UN-Z documento de identidade emitido aqui não é aceito), Portugal (Atenção: SU sem restrição; MO sem restrição; UN-B sem restrição; UN-Z documento de identidade emitido aqui não é aceito), Romênia (Atenção: SU sem restrição; MO sem restrição; UN-B sem restrição; UN-Z documento de identidade emitido aqui não é aceito), Sérvia, Eslováquia (Atenção: SU sem restrição; MO sem restrição; UN-B sem restrição; UN-Z documento de identidade emitido aqui não é aceito), Eslovênia (Atenção: SU sem restrição; MO sem restrição; UN-B sem restrição; UN-Z documento de identidade emitido aqui não é aceito), Espanha (Atenção: SU sem restrição; MO sem restrição; UN-B sem restrição; UN-Z documento de identidade emitido aqui não é aceito), Suécia (Atenção: SU sem restrição; MO sem restrição; UN-B sem restrição; UN-Z documento de identidade emitido aqui não é aceito), Suíça (Atenção: SU sem restrição; MO sem restrição; UN-B sem restrição; UN-Z documento de identidade emitido aqui não é aceito), Tajiquistão, Reino Unido (Atenção: SU sem restrição; MO sem restrição; UN-B sem restrição; UN-Z documento de identidade emitido aqui não é aceito), Vaticano.
- América Latina e Caribe: Argentina, Bahamas, Brasil, Chile, Colômbia, Costa Rica, República Dominicana, Equador, El Salvador, Guatemala, Honduras, México, Panamá, Paraguai, Peru, Uruguai.
- Oriente Médio e Índia: Bahrein, Índia, Israel, Jordânia, Kuwait, Omã, Palestina, Catar, Arábia Saudita, Emirados Árabes Unidos.
- América do Norte: Canadá (Atenção: SU sem restrição; MO sem restrição; UN-B sem restrição; UN-Z documento de identidade emitido aqui não é aceito), Estados Unidos, Porto Rico.
### Na lista da Apple, mas bloqueados para os cartões
Estes estão na lista da Apple, mas os cartões não funcionam neles:
China continental (Parcial: SU bloqueado; MO sem restrição; UN-B sem restrição; UN-Z sem restrição), Belarus (Restrito: SU bloqueado; MO bloqueado; UN-B bloqueado; UN-Z bloqueado), Kosovo (Parcial: SU bloqueado; MO sem restrição; UN-B sem restrição; UN-Z sem restrição), Ucrânia (Parcial: SU bloqueado; MO sem restrição; UN-B bloqueado; UN-Z bloqueado).
---
Source: https://docs.web3card.dev/pt-BR/access/create-business-account/
# Criar uma conta Business
A conta Business é a conta da sua empresa na Web3Card. Quem cria a conta vira o **dono** da empresa na plataforma. Leva alguns minutos e tem três etapas de verificação, todas obrigatórias.
O painel Business fica em `business.web3card.dev`.
## Antes de começar
Tenha três coisas à mão:
- **Acesso ao seu e-mail de trabalho.** Você vai receber um código de 6 dígitos.
- **Um aplicativo autenticador no celular.** Google Authenticator, Microsoft Authenticator, Authy e 1Password funcionam.
- **Um celular que receba SMS.** Você vai receber um código por mensagem de texto.
Depois de confirmar o e-mail, você tem **60 minutos** para terminar as outras duas etapas. A conta e a empresa só passam a existir quando a última etapa termina. Se você parar antes, nada fica salvo.
## Abra o formulário
1. Abra o painel Business. Na tela de login, escolha **Sign up your company**.
2. Preencha o formulário **Create your company account**:
| Campo | Regra |
| --- | --- |
| **Company name** | O nome da empresa, de 2 a 60 caracteres |
| **Email** | O seu e-mail de trabalho. Cada e-mail só pode ter uma conta Business |
| **Password** | No mínimo 12 caracteres, com pelo menos 1 número, 1 letra minúscula e 1 letra maiúscula |
3. Marque **I agree to the Terms of Service and Privacy Policy**.
4. Escolha **Create account**.
As quatro regras da senha ficam verdes na tela conforme você digita, e o botão do olho no campo mostra o que foi digitado. A senha diferencia maiúsculas de minúsculas. Escolha uma que você não usa em nenhum outro lugar.
## Etapa 1 de 3: confirmar o e-mail
A plataforma envia um código de 6 dígitos para o e-mail informado.
1. Abra o e-mail e copie o código.
2. Na tela **Confirm your email**, digite o código em **Code from the email**.
3. Escolha **Confirm email**.
Bom saber:
- O código vale por **15 minutos**.
- **Send a new code** envia outro. Só o código mais novo vale.
- **Depois de 5 códigos errados o cadastro é cancelado.** Preencha o formulário de novo para receber um código novo.
- Se nenhum e-mail chegar depois de você pedir um código novo, escolha **Use a different email** e preencha o formulário de novo.
- O e-mail traz só o código. Nunca traz um link para clicar.
## Etapa 2 de 3: configurar o aplicativo autenticador
Daqui em diante, todo login pede um código do aplicativo autenticador. Uma senha roubada não basta para entrar na sua conta.
1. Na tela **Protect your account**, abra o seu aplicativo autenticador e leia o QR code.
2. Não consegue ler? Abaixo de **Can't scan it? Type this key into the app instead:** a tela mostra uma chave. Digite essa chave no aplicativo. O botão ao lado copia a chave.
3. O aplicativo passa a mostrar um código de 6 dígitos para **Web3Card Business**. Digite o código no campo **2. Enter the 6-digit code the app shows**.
4. Escolha **Continue**.
O código muda a cada 30 segundos. Se um for recusado, espere o próximo.
**Guarde o celular com o aplicativo**
A chave aparece só nesta tela. Depois desta etapa ela nunca mais é mostrada. Se você perder o celular, siga [Perdeu o celular: trocar o autenticador](https://docs.web3card.dev/pt-BR/access/replace-authenticator/).
## Etapa 3 de 3: confirmar o celular
1. Na tela **Confirm your mobile number**, escolha o seu país em **Country** e digite o número com o DDD em **Mobile number**. Se o seu país não está na lista, escolha **Other country** e digite o número inteiro, começando pelo código do país.
2. Escolha **Send code by SMS**.
3. Na tela **Enter the code we texted you**, digite o código em **Code from the SMS**. A tela mostra o número que recebeu o código, com parte dele escondida.
4. Escolha **Finish creating account**.
Bom saber:
- O código do SMS vale por **10 minutos** e deixa de valer depois de **5 tentativas erradas**. Quando isso acontece a tela volta para o celular, e você pede outro SMS.
- Você pode receber até **3 SMS** por cadastro, com pelo menos 60 segundos entre um e outro. O botão mostra a contagem: **Send a new code in 42s**.
- Digitou o número errado? Escolha **Wrong number? Change it**. Abre a tela **Send the code again**. Enviar para o número novo gasta um dos 3 SMS.
- Se você recarregar a página, **Send a new code** pede o número de novo.
- Se os 3 SMS acabarem, aquele cadastro não tem como terminar. Comece de novo pelo formulário.
- Cada celular só pode ter uma conta Business.
- Este é o único SMS que a plataforma envia para você. O login nunca usa SMS.
## Pronto, você entrou
Quando o código do SMS é aceito, a empresa e a sua conta são criadas e você já entra logado. Essa primeira sessão dura 1 dia. A tela Home do painel abre com um aviso que diz em que etapa a sua empresa está.
O que abre em seguida está em [Do cadastro ao lançamento](https://docs.web3card.dev/pt-BR/platform/path-to-launch/).
## Se você parar no meio
| Onde você parou | O que acontece quando você volta |
| --- | --- |
| Antes de confirmar o e-mail | Entre com o e-mail e a senha que você escolheu. A plataforma leva você à tela **Confirm your email**. Também dá para preencher o formulário de novo: o cadastro novo substitui o anterior |
| Depois de confirmar o e-mail, no mesmo navegador | Recarregar a tela mostra a mesma etapa. Se você abrir o endereço principal do painel, aparece o login: entre com o e-mail e a senha, e a plataforma leva você de volta à etapa em que parou |
| Depois de 60 minutos | A tela mostra **This step has expired. Please start again.** e leva você ao formulário de cadastro. Nada da primeira tentativa ficou salvo |
| Em outro navegador ou aparelho | Ao entrar aparece **Your sign-up was not finished and can no longer be continued here. Create the account again.** Escolha **Sign up your company** |
## Entrar em uma empresa que já existe
Quem faz parte da equipe não abre uma empresa nova. Vai entrar por convite do dono e passar pelas mesmas três etapas.
**Situação: em desenvolvimento**
As telas de convite estão sendo construídas. Esta seção ganha o passo a passo quando o dono puder criar convites no painel Business.
## Mensagens que podem aparecer
| Mensagem | O que significa | O que fazer |
| --- | --- | --- |
| This email already has an account. Log in instead. | Já existe uma conta Business com esse e-mail | [Entre](https://docs.web3card.dev/pt-BR/access/sign-in/) ou [troque a senha](https://docs.web3card.dev/pt-BR/access/reset-password/) |
| That code is not right or has expired. Check it and try again. | O código está errado ou venceu | Confira o código ou peça outro. Depois de 5 códigos de e-mail errados, preencha o formulário de novo |
| That code can no longer be used. Ask for a new one. | O código do SMS venceu ou chegou a 5 tentativas erradas | Peça outro SMS |
| This mobile number already belongs to an account. Use another one. | O número já está em uso por outra conta Business | Use outro número |
| Wait a minute before asking for another SMS. | Passaram menos de 60 segundos desde o último SMS | Espere a contagem da tela |
| No more SMS can be sent for now. Try again later. | Um limite de SMS foi atingido | Veja [os limites](https://docs.web3card.dev/pt-BR/access/security-and-limits/#sms). Se os 3 SMS deste cadastro acabaram, comece de novo pelo formulário |
| This step has expired. Please start again. | Passaram mais de 60 minutos, ou a etapa não existe mais | Crie a conta de novo |
| Too many attempts. Wait a few minutes and try again. | Tentativas demais em pouco tempo a partir da sua rede | Espere alguns minutos |
Todas as mensagens das telas de acesso estão em [Regras de segurança e limites](https://docs.web3card.dev/pt-BR/access/security-and-limits/#messages).
---
Source: https://docs.web3card.dev/pt-BR/access/create-personal-account/
# Criar uma conta Pessoal
A conta Pessoal é a conta de quem usa o cartão. Você cria a conta no app da empresa que oferece o programa de cartões, no endereço dessa empresa.
Este guia é escrito para o usuário final. As empresas podem indicar esta página aos seus usuários.
Cada empresa tem o seu endereço. O app da própria Web3Card fica em `wallet.web3card.app`.
## Antes de começar
Tenha três coisas à mão:
- **Acesso ao seu e-mail.** Você vai receber um código de 6 dígitos.
- **Um aplicativo autenticador no celular.** Google Authenticator, Microsoft Authenticator, Authy e 1Password funcionam.
- **Um celular que receba SMS.** Você vai receber um código por mensagem de texto.
Depois de confirmar o e-mail, você tem **60 minutos** para terminar as outras duas etapas. A conta só passa a existir quando a última etapa termina.
## Abra o formulário
1. Abra o endereço do app. Na tela de login, escolha **Sign up**.
2. Preencha o formulário **Create your account**:
| Campo | Regra |
| --- | --- |
| **Email** | Cada e-mail pode ter uma conta no app de cada empresa |
| **Password** | No mínimo 12 caracteres, com pelo menos 1 número, 1 letra minúscula e 1 letra maiúscula |
| **Invite code (optional)** | Se você recebeu um código de convite, digite aqui. Pode ficar vazio |
3. Marque **I agree to the Terms of Service and Privacy Policy**.
4. Escolha **Create account**.
As quatro regras da senha ficam verdes na tela conforme você digita. A senha diferencia maiúsculas de minúsculas. Escolha uma que você não usa em nenhum outro lugar.
## Etapa 1 de 3: confirmar o e-mail
1. Abra o e-mail que você recebeu e copie o código de 6 dígitos.
2. Na tela **Confirm your email**, digite o código em **Code from the email**.
3. Escolha **Confirm email**.
Bom saber:
- O código vale por **15 minutos**.
- **Send a new code** envia outro. Só o código mais novo vale.
- **Depois de 5 códigos errados o cadastro é cancelado.** Preencha o formulário de novo para receber um código novo.
- Se nenhum e-mail chegar depois de você pedir um código novo, escolha **Use a different email** e preencha o formulário de novo.
- O e-mail traz só o código. Nunca traz um link para clicar.
## Etapa 2 de 3: configurar o aplicativo autenticador
Todo login pede um código do aplicativo autenticador. Uma senha roubada não basta para entrar na sua conta.
1. Na tela **Protect your account**, abra o seu aplicativo autenticador e leia o QR code.
2. Não consegue ler? Abaixo de **Can't scan it? Type this key into the app instead:** a tela mostra uma chave. Digite essa chave no aplicativo.
3. O aplicativo passa a mostrar um código de 6 dígitos com o nome da empresa. Digite o código no campo **2. Enter the 6-digit code the app shows**.
4. Escolha **Continue**.
O código muda a cada 30 segundos. Se um for recusado, espere o próximo.
**Guarde o celular com o aplicativo**
A chave aparece só nesta tela. Se você perder o celular depois, siga [Perdeu o celular: trocar o autenticador](https://docs.web3card.dev/pt-BR/access/replace-authenticator/).
## Etapa 3 de 3: confirmar o celular
1. Na tela **Confirm your mobile number**, escolha o seu país em **Country** e digite o número com o DDD em **Mobile number**. Se o seu país não está na lista, escolha **Other country** e digite o número inteiro, começando pelo código do país.
2. Escolha **Send code by SMS**.
3. Na tela **Enter the code we texted you**, digite o código em **Code from the SMS**. A tela mostra o número que recebeu o código, com parte dele escondida.
4. Escolha **Finish creating account**.
Bom saber:
- O código do SMS vale por **10 minutos** e deixa de valer depois de **5 tentativas erradas**. Quando isso acontece a tela volta para o celular, e você pede outro SMS.
- Você pode receber até **3 SMS** por cadastro, com pelo menos 60 segundos entre um e outro. O botão mostra a contagem: **Send a new code in 42s**.
- Digitou o número errado? Escolha **Wrong number? Change it**. Enviar para o número novo gasta um dos 3 SMS.
- Se os 3 SMS acabarem, aquele cadastro não tem como terminar. Comece de novo pelo formulário.
- Este é o único SMS que você recebe do app. O login nunca usa SMS.
## Pronto, você entrou
Quando o código do SMS é aceito, a sua conta é criada e você já entra logado. Essa primeira sessão dura 1 dia.
## Uma conta por empresa
A sua conta pertence ao app em que você a criou.
- O seu e-mail e o seu celular podem ser usados uma vez no app de cada empresa.
- Se você usa os apps de duas empresas diferentes, tem duas contas independentes. Cada uma tem a sua senha e a sua entrada no aplicativo autenticador.
## Se você parar no meio
| Onde você parou | O que acontece quando você volta |
| --- | --- |
| Antes de confirmar o e-mail | Entre com o e-mail e a senha que você escolheu. O app leva você à tela **Confirm your email**. Também dá para preencher o formulário de novo |
| Depois de confirmar o e-mail, no mesmo navegador | Recarregar a tela mostra a mesma etapa. Se você abrir o endereço principal do app, aparece o login: entre com o e-mail e a senha, e o app leva você de volta à etapa em que parou |
| Depois de 60 minutos | A tela mostra **This step has expired. Please start again.** e leva você ao formulário de cadastro |
| Em outro navegador ou aparelho | Ao entrar aparece **Your sign-up was not finished and can no longer be continued here. Create the account again.** Escolha **Sign up** |
## Se o endereço não abrir
| O que você vê | O que significa | O que fazer |
| --- | --- | --- |
| **This address is not active** | O endereço digitado não está ligado a uma empresa | Confira o endereço com a empresa que oferece o cartão |
| **We could not load the page** | O app não conseguiu falar com o servidor | Confira a sua conexão e escolha **Try again** |
## Mensagens que podem aparecer
| Mensagem | O que fazer |
| --- | --- |
| This email already has an account. Sign in instead. | [Entre](https://docs.web3card.dev/pt-BR/access/sign-in/) ou [troque a senha](https://docs.web3card.dev/pt-BR/access/reset-password/) |
| That code is not right or has expired. Check it and try again. | Confira o código ou peça outro. Depois de 5 códigos de e-mail errados, preencha o formulário de novo |
| That code can no longer be used. Ask for a new one. | O código do SMS venceu ou chegou a 5 tentativas erradas. Peça outro SMS |
| This mobile number already belongs to an account. Use another one. | Use outro número |
| Wait a minute before asking for another SMS. | Espere a contagem da tela |
| No more SMS can be sent for now. Try again later. | Veja [os limites](https://docs.web3card.dev/pt-BR/access/security-and-limits/#sms). Se os 3 SMS deste cadastro acabaram, comece de novo pelo formulário |
| This step has expired. Please start again. | Crie a conta de novo |
| Too many attempts. Wait a few minutes and try again. | Espere alguns minutos |
Todas as mensagens das telas de acesso estão em [Regras de segurança e limites](https://docs.web3card.dev/pt-BR/access/security-and-limits/#messages).
---
Source: https://docs.web3card.dev/pt-BR/access/sign-in/
# Entrar e sair
O login funciona do mesmo jeito no painel Business e no app Pessoal. Sempre tem duas partes: a senha e, em seguida, um código do aplicativo autenticador.
## Como entrar
1. Abra a tela de login. No painel Business o título dela é **Log in to Web3Card Business**. Em um app Pessoal o título é **Log in to your**, o nome da empresa e **account**.
2. Digite o seu **Email** e a sua **Password**.
3. **Stay signed in for 7 days** já vem marcado. Deixe assim se o aparelho é seu. Desmarque em computador compartilhado.
4. Escolha **Sign In**.
5. Na tela **Enter your authenticator code**, abra o aplicativo autenticador e digite o código em **6-digit code from the app**.
6. Escolha **Sign In**.
Você tem **5 minutos** para digitar o código do autenticador depois que a senha é aceita. Passado esse tempo, comece de novo pela senha.
No painel Business, se você abriu um endereço de dentro do painel antes de entrar, cai nesse endereço depois do código. O app Pessoal abre sempre na tela Home.
## Como sair
- **Painel Business.** No pé do menu lateral, escolha o seu nome. O menu mostra o seu e-mail e **Sign out**.
- **App Pessoal.** No pé do menu, escolha o seu e-mail e depois **Sign out**. A tela **Account** também tem o botão **Sign out**.
Depois de sair, abre a tela de login.
## Por quanto tempo você fica conectado
| Opção na tela de login | A sessão dura |
| --- | --- |
| **Stay signed in for 7 days** marcado | 7 dias |
| Desmarcado | 1 dia |
A primeira sessão, logo depois de criar a conta, dura 1 dia.
A sessão também termina na hora quando:
- você sai da conta
- a senha da conta é trocada
- o autenticador da conta é trocado
A sessão também pode terminar quando a plataforma é atualizada. Se acontecer, entre de novo.
Quando a sessão termina, a próxima tela que você abrir leva de volta ao login.
## Sobre o código do autenticador
- **Cada código vale uma vez só.** Se você acabou de usar um código, espere o aplicativo mostrar o próximo.
- **O código muda a cada 30 segundos.** A plataforma também aceita o código logo anterior e o logo seguinte ao atual, para tolerar pequenas diferenças de relógio.
- **Depois de 5 códigos errados o login é cancelado.** A tentativa seguinte mostra **This step has expired. Please start again.** e você recomeça pela senha.
**Os códigos são sempre recusados?**
Confira o relógio do celular. Os códigos do autenticador dependem da hora exata. Deixe a data e a hora do celular no automático e tente de novo.
## Se você não terminou de criar a conta
- **Você não confirmou o e-mail.** Entrar leva você direto à tela **Confirm your email**.
- **Você confirmou o e-mail e parou depois.** No mesmo navegador, entrar leva você de volta à etapa em que parou. Em outro navegador a tela mostra **Your sign-up was not finished and can no longer be continued here. Create the account again.**
## Se algo der errado
| Mensagem | O que significa | O que fazer |
| --- | --- | --- |
| Invalid email or password. | O e-mail ou a senha não conferem. A resposta é a mesma exista ou não a conta | Confira os dois. A senha diferencia maiúsculas de minúsculas. Ou [troque a senha](https://docs.web3card.dev/pt-BR/access/reset-password/) |
| That code is not right or has expired. Check it and try again. | O código do autenticador está errado ou já foi usado | Espere o próximo código |
| This step has expired. Please start again. | Passaram mais de 5 minutos desde a senha, ou foram digitados 5 códigos errados | Entre de novo |
| Too many attempts. Wait a few minutes and try again. | Tentativas demais em pouco tempo a partir da sua rede | Espere alguns minutos |
| We could not load the page | O app não conseguiu falar com o servidor | Confira a sua conexão e escolha **Try again** |
## Veja também
- Esqueceu a senha? Veja [Trocar a senha](https://docs.web3card.dev/pt-BR/access/reset-password/).
- Perdeu o celular com o aplicativo autenticador? Veja [Perdeu o celular: trocar o autenticador](https://docs.web3card.dev/pt-BR/access/replace-authenticator/).
- Todos os prazos, limites e mensagens estão em [Regras de segurança e limites](https://docs.web3card.dev/pt-BR/access/security-and-limits/).
---
Source: https://docs.web3card.dev/pt-BR/access/reset-password/
# Trocar a senha
Se você esqueceu a senha, escolhe uma nova com um código de 6 dígitos enviado para o seu e-mail. A plataforma nunca envia link para isso. Funciona do mesmo jeito no painel Business e no app Pessoal.
Este também é o caminho para trocar uma senha que você ainda lembra: saia da conta e escolha **Forgot password?**
## Escolha uma senha nova
1. Na tela de login, escolha **Forgot password?**
2. Na tela **Reset your password**, digite o **Email** da sua conta e escolha **Send code**.
3. Abra o e-mail e copie o código de 6 dígitos.
4. Na tela **Choose a new password**, digite o código em **Code from the email** e a senha nova em **New password**.
5. Escolha **Save new password**.
6. Na tela **Password changed**, escolha **Go to log in** e [entre](https://docs.web3card.dev/pt-BR/access/sign-in/) com a senha nova. A plataforma pede o código do autenticador, como sempre.
A senha nova segue as mesmas regras da primeira: no mínimo 12 caracteres, com pelo menos 1 número, 1 letra minúscula e 1 letra maiúscula.
## Sobre o código
- Vale por **10 minutos**.
- Vale **uma vez**.
- Deixa de valer depois de **5 tentativas erradas**.
- **Send a new code** envia outro. Só o código mais novo vale.
Por privacidade, a tela mostra a mesma mensagem exista ou não uma conta com o e-mail digitado. Se o e-mail não chegar, confira o endereço e a caixa de spam.
## O que acontece quando a senha muda
- **Todas as sessões abertas da conta são encerradas**, em todos os aparelhos. Cada aparelho precisa entrar de novo.
- **Você recebe um e-mail** avisando que a senha foi trocada. Se não foi você, fale com o suporte na hora.
- **A troca do autenticador fica travada por 24 horas.** Veja [Perdeu o celular: trocar o autenticador](https://docs.web3card.dev/pt-BR/access/replace-authenticator/).
## O que não muda
Trocar a senha não muda o seu aplicativo autenticador. Você continua precisando do código dele para entrar com a senha nova.
---
Source: https://docs.web3card.dev/pt-BR/access/replace-authenticator/
# Perdeu o celular: trocar o autenticador
Se você perdeu ou trocou o celular que tem o aplicativo autenticador, pode configurar um novo. Você precisa da senha e de acesso ao seu e-mail. Funciona do mesmo jeito no painel Business e no app Pessoal.
## O que você precisa
- **A sua senha.** A troca começa depois que a senha é aceita.
- **Acesso ao e-mail da conta.** Você vai receber um código de 6 dígitos.
- **Um aplicativo autenticador no celular novo.**
- **24 horas desde que a senha foi criada ou trocada pela última vez.** Vale também para conta nova: no primeiro dia o autenticador não pode ser trocado. Veja [o motivo](#why-the-24-hour-wait) mais abaixo.
Você não precisa de SMS, e não há códigos de recuperação para guardar.
## Troque o autenticador
1. Na tela de login, digite o seu **Email** e a sua **Password** e escolha **Sign In**.
2. Na tela **Enter your authenticator code**, escolha **I lost my phone**. Você tem 5 minutos para fazer isso depois que a senha é aceita.
3. A plataforma envia um código de 6 dígitos para o seu e-mail. Na tela **Check your email**, digite o código em **Code from the email** e escolha **Continue**.
4. Na tela **Set up your new authenticator**, leia o QR code com o aplicativo autenticador do celular novo. Não consegue ler? Digite a chave que aparece abaixo do QR code.
5. Digite o código no campo **2. Enter the 6-digit code the app shows** e escolha **Finish and sign in**.
Bom saber:
- Você tem **15 minutos** para digitar o código do e-mail e, depois, mais **15 minutos** para configurar o aplicativo novo.
- **5 códigos errados** em qualquer uma das duas etapas cancelam a troca. A tela mostra **This step has expired. Please start again.** e você recomeça pela senha.
- Não há botão para reenviar o e-mail. Se o e-mail não chegar ou o código vencer, escolha **Back to log in**, entre com a senha e escolha **I lost my phone** de novo.
## O que acontece quando você termina
- **O autenticador antigo para de funcionar** naquele instante.
- **Todas as sessões abertas da conta são encerradas**, em todos os aparelhos.
- **Você recebe um e-mail** avisando que o autenticador foi trocado. Se não foi você, fale com o suporte na hora.
- Você já entra logado no aparelho em que fez a troca.
## Por que esperar 24 horas
O autenticador só pode ser trocado 24 horas depois de a senha ser criada ou trocada. Se você tentar antes, este aviso aparece abaixo do campo, na tela **Enter your authenticator code**:
> For your security, the authenticator can only be replaced 24 hours after the password was created or changed. Try again later.
Isso protege você quando alguém invade o seu e-mail. Sem a espera, essa pessoa poderia trocar a sua senha e o seu autenticador em sequência e tomar a conta em minutos. Com a espera, você recebe o e-mail de troca de senha e tem um dia inteiro para reagir.
## O que ainda não dá para trocar
O celular confirmado no cadastro não pode ser trocado. No app Pessoal, a tela **Account** mostra o número em **Mobile number**, sem botão de editar. A plataforma usa SMS uma vez só, quando a conta é criada, então perder o acesso àquele número não tranca a sua conta.
---
Source: https://docs.web3card.dev/pt-BR/access/security-and-limits/
# Regras de segurança e limites
Esta página é a referência de todas as regras de acesso à conta. As regras são as mesmas no painel Business e no app Pessoal.
## Senha
| Regra | |
| --- | --- |
| Tamanho | No mínimo 12 caracteres |
| Números | Pelo menos 1 (0-9) |
| Minúsculas | Pelo menos 1 (a-z) |
| Maiúsculas | Pelo menos 1 (A-Z) |
| Maiúsculas e minúsculas | A senha diferencia umas das outras |
## Códigos
Todo código tem 6 dígitos.
| Código | Chega por | Vale por | Na 5ª tentativa errada |
| --- | --- | --- | --- |
| Confirmação do e-mail no cadastro | E-mail | 15 minutos | O cadastro é cancelado. Preencha o formulário de novo |
| Confirmação do celular no cadastro | SMS | 10 minutos | O código deixa de valer. Peça outro SMS, se ainda tiver |
| Login | Aplicativo autenticador | 30 segundos, uma vez | O login é cancelado. Digite a senha de novo |
| Troca de senha | E-mail | 10 minutos, uma vez | O código deixa de valer. Peça outro |
| Troca do autenticador | E-mail e depois o aplicativo novo | 15 minutos para cada um | A troca é cancelada. Recomece pela senha |
Quando você pede um código novo por e-mail, o anterior deixa de valer.
## SMS
O SMS é usado uma vez na vida da conta: para confirmar o celular no cadastro.
| Limite | Valor |
| --- | --- |
| Tempo entre um SMS e o seguinte | 60 segundos |
| SMS por cadastro | 3. Trocar o número gasta um deles |
| SMS para o mesmo número | 3 a cada 24 horas, contadas a partir do primeiro |
Quando um limite é atingido, a tela pede para tentar mais tarde. Se os 3 SMS de um cadastro acabarem, aquele cadastro não tem como terminar: comece de novo pelo formulário.
## Celular
- O número é guardado no formato internacional, com o código do país.
- Tem de 8 a 15 dígitos, contando o código do país.
- Escolha o país na lista, ou **Other country** para digitar o número inteiro.
- O zero na frente do número local é tirado sozinho.
- O número confirmado no cadastro não pode ser trocado.
## Tempo para terminar cada fluxo
| Fluxo | Tempo |
| --- | --- |
| Cadastro, contado a partir da confirmação do e-mail | 60 minutos |
| Login, entre a senha e o código do autenticador | 5 minutos |
| Troca do autenticador | 15 minutos para o código do e-mail e mais 15 minutos para configurar o aplicativo novo |
Quando o tempo acaba, o fluxo recomeça do início.
## Sessões
| | |
| --- | --- |
| Duração padrão | 1 dia |
| Com **Stay signed in for 7 days** | 7 dias |
| Primeira sessão, logo depois do cadastro | 1 dia |
| Sair da conta | Encerra a sessão na hora |
| Senha trocada | Encerra todas as sessões da conta |
| Autenticador trocado | Encerra todas as sessões da conta |
| Atualização da plataforma | Pode encerrar a sessão. Entre de novo |
A sessão só vale onde foi criada. Uma sessão do painel Business não funciona em um app Pessoal, e uma sessão no app de uma empresa não funciona no app de outra.
## Uma conta por e-mail e por celular
| | Painel Business | App Pessoal |
| --- | --- | --- |
| E-mail | Uma conta no painel inteiro | Uma conta no app de cada empresa |
| Celular | Uma conta no painel inteiro | Uma conta no app de cada empresa |
## Tentativas demais
A plataforma limita quantas vezes o login, os códigos e o cadastro podem ser tentados em pouco tempo a partir da mesma rede. Quando o limite é atingido, a tela mostra **Too many attempts. Wait a few minutes and try again.**
## O que a plataforma nunca faz
- **Nunca envia link por e-mail.** Todo e-mail traz um código de 6 dígitos, que você digita no site que já está aberto, ou é só um aviso. Se você receber um e-mail com link para entrar ou para trocar a senha, ele não veio da plataforma.
- **Nunca pede a sua senha nem os seus códigos** por e-mail, por telefone ou por chat.
- **Nunca mostra de novo a chave do autenticador** depois da tela de configuração.
- **Nunca envia SMS depois do cadastro.**
## E-mails que você pode receber
Todos os e-mails estão em inglês. O remetente é o nome da empresa dona do app que você usa. No painel Business o remetente é Web3Card. O assunto começa com esse mesmo nome.
| O assunto termina com | Quando | O que traz |
| --- | --- | --- |
| Confirm your email | Você cria uma conta ou pede um código novo | Um código que vale por 15 minutos |
| Code to reset your password | Você escolhe **Forgot password?** | Um código que vale por 10 minutos, uma vez |
| Code to change your authenticator app | Você escolhe **I lost my phone** | Um código que vale por 15 minutos |
| Your password was changed | A senha da conta foi trocada | Um aviso, sem código |
| Your authenticator app was changed | O autenticador da conta foi trocado | Um aviso, sem código |
O SMS tem uma linha só: o nome da empresa, o código e por quanto tempo ele vale.
Se um e-mail não chegar, olhe a caixa de spam e peça um código novo. Se você receber um aviso de algo que não fez, fale com o suporte na hora.
## Mensagens das telas de acesso
**Ao preencher um campo**
| Mensagem | Quando aparece | O que fazer |
| --- | --- | --- |
| Enter a valid email address. | O e-mail não tem formato de endereço de e-mail | Corrija o endereço |
| Enter your password. | Login com a senha vazia | Digite a senha |
| The password does not meet the rules below. | Falta alguma das quatro regras da senha | Olhe as regras que ainda não ficaram verdes |
| Enter the name of your company. | Cadastro Business com nome da empresa de menos de 2 caracteres | Digite o nome |
| You need to accept the terms to continue. | Cadastro sem marcar a caixa dos termos | Marque a caixa |
| Enter the 6-digit code. | Código com menos de 6 dígitos | Digite os 6 dígitos |
| Enter your mobile number, with the area code. | O número está curto ou longo demais | Confira o número |
| Enter the full number, starting with the country code. | Com **Other country**, o número está fora do formato | Digite o código do país e o número |
**Quando a plataforma responde**
| Mensagem | Quando aparece | O que fazer |
| --- | --- | --- |
| Invalid email or password. | O e-mail ou a senha não conferem | Confira os dois, ou [troque a senha](https://docs.web3card.dev/pt-BR/access/reset-password/) |
| This email already has an account. Log in instead. | Cadastro no painel Business com e-mail que já tem conta | [Entre](https://docs.web3card.dev/pt-BR/access/sign-in/) |
| This email already has an account. Sign in instead. | Cadastro em um app Pessoal com e-mail que já tem conta | [Entre](https://docs.web3card.dev/pt-BR/access/sign-in/) |
| That code is not right or has expired. Check it and try again. | Um código está errado, venceu ou já foi usado | Confira, espere o próximo ou peça outro |
| That code can no longer be used. Ask for a new one. | O código do SMS venceu ou chegou a 5 tentativas erradas | Peça outro SMS |
| This mobile number already belongs to an account. Use another one. | O número já está em uso | Use outro número |
| Wait a minute before asking for another SMS. | Passaram menos de 60 segundos desde o último SMS | Espere a contagem |
| No more SMS can be sent for now. Try again later. | Um [limite de SMS](#sms) foi atingido | Tente mais tarde, ou comece de novo pelo formulário |
| This step has expired. Please start again. | O tempo do fluxo acabou, ou foram digitados 5 códigos errados | Recomece o fluxo |
| Your sign-up was not finished and can no longer be continued here. Create the account again. | Você entrou com um cadastro que não terminou, em outro navegador | Crie a conta de novo |
| Too many attempts. Wait a few minutes and try again. | Tentativas demais em pouco tempo | Espere alguns minutos |
| Check the fields and try again. | A plataforma recusou algum campo | Confira o que foi digitado |
| Could not reach the server. Check your connection and try again. | Sem conexão, ou sem resposta | Confira a sua conexão |
**Avisos que não são erro**
| Mensagem | Quando aparece |
| --- | --- |
| New code sent. | Depois de **Send a new code** na tela do SMS |
| If this email is waiting for confirmation, a new code is on its way. | Depois de **Send a new code** na tela **Confirm your email** |
| If there is an account for this email, a new code is on its way. | Depois de **Send a new code** na tela **Choose a new password** |
| Key copied | Depois do botão que copia a chave do autenticador |
**Páginas no lugar da tela**
| Página | Quando aparece | O que fazer |
| --- | --- | --- |
| This address is not active | O endereço de um app Pessoal não está ligado a uma empresa | Confira o endereço com a empresa que oferece o cartão |
| We could not load the page | O app não conseguiu falar com o servidor | Confira a sua conexão e escolha **Try again** |
---
Source: https://docs.web3card.dev/pt-BR/api/overview/
# Visão geral da API v2
A API da Web3Card permite que os seus próprios sistemas operem o seu programa de cartões por código: usuários, verificação de identidade, as contas que abastecem os cartões, os cartões em si, transações e eventos.
A API cobre o programa de cartões. Acesso à conta, equipe, marca e domínio são cuidados no painel Business e não fazem parte dela.
**Situação: planejado**
A API v2 está desenhada e ainda não foi construída. Nenhuma rota está publicada. Esta página descreve o que a API é e os princípios que ela segue, e os detalhes ainda podem mudar. A referência completa, com cada rota, pedido e resposta, será publicada neste capítulo quando a primeira versão puder ser testada.
## Uma API para o seu programa
A Web3Card funciona como um hub ligado a vários parceiros emissores de cartão. Um programa pode rodar em um parceiro ou em mais de um.
Você integra uma vez, com uma API. Usuários, cartões e transações têm o mesmo formato seja qual for a instituição por trás.
Nem toda função existe em todo programa. Funções como limite de gasto por cartão, ou devolver saldo do cartão para a conta, dependem do parceiro por trás do programa. A API diz quais funções o seu programa tem e responde com um erro próprio quando você chama uma que ele não tem.
## Princípios do desenho
Estes são os princípios sobre os quais a API foi desenhada.
| Princípio | O que significa para a sua integração |
| --- | --- |
| **Operações assíncronas** | Um pedido que cria ou altera algo na instituição parceira, como pedir ou congelar um cartão, devolve uma operação, que você acompanha até terminar. Pedidos que não dependem do parceiro respondem na hora |
| **Repetição segura** | Todo pedido de escrita leva uma chave escolhida por você. Mandar o mesmo pedido duas vezes com a mesma chave nunca repete o efeito |
| **Eventos assinados** | A plataforma avisa o seu sistema quando algo acontece, como um cartão ficar ativo ou uma compra ser feita. Cada aviso é assinado, para você confirmar que veio da plataforma |
| **O mesmo modelo em todo programa** | Usuários, cartões e transações têm o mesmo formato e os mesmos estados em todos os programas |
| **Dados do cartão protegidos** | A plataforma não guarda número completo de cartão, código de segurança nem PIN |
## O que a API vai cobrir
| Área | O que você vai fazer com ela |
| --- | --- |
| Usuários | Criar e consultar os usuários do seu programa |
| Verificação de identidade | Iniciar a verificação de um usuário e acompanhar o resultado |
| Produtos | Listar os produtos de cartão disponíveis no seu programa |
| Contas de saldo | Criar a conta que abastece os cartões, acompanhar o saldo, depositar e sacar |
| Cartões | Pedir, congelar, descongelar e encerrar cartões |
| Recarga e retirada | Mover saldo da conta para um cartão e de um cartão de volta para a conta |
| Limites e controles de gasto | Definir limites e restringir tipos de loja, onde o programa tiver |
| Dados do cartão | Obter os dados completos de um cartão para mostrar ao titular, por um pedido de uso único |
| Códigos de verificação | Receber o código que a loja pede em uma compra online |
| Operações | Acompanhar cada pedido que você fez até ele terminar |
| Transações | Listar compras, estornos, depósitos e recargas |
| Eventos | Receber avisos nos seus próprios sistemas |
| Simulação | Gerar compras, estornos e liquidações de teste |
A lista pode mudar antes de a referência ser publicada.
## O que vem a seguir neste capítulo
1. Autenticação e ambientes
2. Convenções: pedidos, respostas, erros e repetição
3. A referência de cada área acima
4. Eventos e como conferir a assinatura
5. Guias passo a passo dos fluxos mais comuns
Cada item é publicado quando puder ser testado.
---
Source: https://docs.web3card.dev/pt-BR/getting-started/quickstart/
# 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 [contact@web3card.dev](mailto:contact@web3card.dev) 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](https://docs.web3card.dev/pt-BR/api/overview/) 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`:
```bash
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:
```bash
curl -X POST https://api.web3card.dev/v1/users \
-H "Authorization: Bearer w3c_test_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"email": "ana@example.com",
"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:
```bash
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](https://docs.web3card.dev/pt-BR/api-reference/users-and-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:
```bash
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
```bash
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:
```json
{
"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](https://docs.web3card.dev/pt-BR/guides/top-ups/) ou assine os [webhooks](https://docs.web3card.dev/pt-BR/guides/webhooks/) para receber os eventos na hora.
---
Source: https://docs.web3card.dev/pt-BR/getting-started/integration-models/
# Modelos de integração
A Web3Card oferece dois modelos de integração. Os dois rodam na mesma infraestrutura e na mesma API; a diferença é quanto da experiência do cartão leva o seu próprio desenho.
**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](https://docs.web3card.dev/pt-BR/api/overview/) a substitui, e a plataforma hoje funciona como descrito no resto deste manual.
## White-label
O caminho mais rápido para lançar. O seu programa usa uma arte de cartão do catálogo de layouts pré-aprovados do emissor parceiro, com o nome do seu projeto junto.
- Arte do cartão escolhida entre layouts pré-certificados
- Aprovação rápida do programa, porque os layouts já estão homologados com a bandeira
- Cartões virtuais e físicos
- Acesso completo à API: usuários, cofres, cartões, transações e webhooks
**Melhor para:** projetos que querem lançar um programa de cartões em semanas, não em meses.
## Personalizado
Um programa feito sob medida. O desenho do cartão é 100% seu, produzido com a nossa equipe de design e enviado à Visa para aprovação da arte.
- Layout exclusivo do cartão, desenhado com a sua marca
- Cuidamos do processo de aprovação da arte com a Visa de ponta a ponta
- Tudo o que o White-label inclui
- Suporte dedicado à implementação
**Melhor para:** projetos já estabelecidos, em que o próprio cartão é uma afirmação da marca.
## Comparando os modelos
| | White-label | Personalizado |
| --- | --- | --- |
| Arte do cartão | Layouts pré-aprovados do emissor parceiro | Feita sob medida, com o seu desenho |
| Aprovação da arte pela bandeira | Não precisa (pré-certificada) | Conduzida pela nossa equipe |
| Prazo para lançar | Semanas | Depende da aprovação da arte |
| Cartões virtuais | ✓ | ✓ |
| Cartões físicos | ✓ | ✓ |
| Acesso à API | Completo | Completo |
| Suporte | Onboarding dedicado | Equipe de implementação dedicada |
Planos e preços estão em [web3card.dev](https://web3card.dev/#pricing).
---
Source: https://docs.web3card.dev/pt-BR/getting-started/onboarding-flow/
# Fluxo de entrada
Esta página descreve o caminho completo de um portador de cartão no seu programa, do cadastro ao primeiro pagamento. Cada passo corresponde a chamadas de API específicas, para você montar o fluxo inteiro dentro do seu produto.
**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](https://docs.web3card.dev/pt-BR/api/overview/) a substitui, e a plataforma hoje funciona como descrito no resto deste manual.
## Visão geral do fluxo
```
Signup → Wallet link → KYC → Vault deployment → Card creation → Top-up → First payment
```
## 1. Cadastro
Crie o usuário com o e-mail dele. O e-mail é confirmado com um código de uso único enviado pela plataforma.
- `POST /users`: cria o usuário
- `POST /users/{id}/email/verify`: confirma o código
## 2. Carteira
O usuário prova que a carteira é dele assinando uma mensagem (Sign-In with Ethereum). A carteira passa a ser a identidade de acesso do usuário e a dona do cofre dele.
- `POST /auth/nonce`: gera a mensagem a assinar
- `POST /auth/verify`: confere a assinatura SIWE
## 3. KYC
A verificação de identidade é exigida pela bandeira e pelo emissor. A Web3Card oferece um fluxo de verificação hospedado, que você pode embutir ou abrir por redirecionamento.
- `POST /users/{id}/kyc/session`: abre uma sessão de verificação
- Webhook `kyc.approved` ou `kyc.rejected`: avisa o resultado
## 4. Implantação do cofre
Com o KYC aprovado, implante o cofre multisig individual do usuário na rede escolhida. A carteira do usuário fica registrada como dona; o operador de liquidação entra como cossignatário só para as liquidações autorizadas do cartão.
- `POST /vaults`: implanta o cofre
- `GET /vaults/{id}`: consulta a situação da implantação
## 5. Criação do cartão
Crie um cartão virtual na hora, ou abra o pedido de um cartão físico com entrega no mundo todo.
- `POST /cards`: cria um cartão virtual
- `POST /card-orders`: pede um cartão físico
## 6. Recarga
O usuário abastece o cofre transferindo USDC, USDT ou o token do seu projeto para o endereço do cofre na rede escolhida. As mudanças de saldo chegam por webhook.
## 7. Primeiro pagamento
O cartão está ativo. Os pagamentos são autorizados na hora contra o saldo do cofre, e cada transação fica disponível pela API e pelos webhooks.
Para os detalhes de cada etapa, veja a seção de [guias](https://docs.web3card.dev/pt-BR/guides/create-virtual-cards/).
---
Source: https://docs.web3card.dev/pt-BR/concepts/cards/
# Cartões
Um Web3Card é um cartão Visa com a marca do seu projeto, emitido por uma instituição parceira e com um cofre na rede por trás. Os cartões vêm em duas formas e têm o mesmo ciclo de vida e a mesma API.
**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](https://docs.web3card.dev/pt-BR/api/overview/) a substitui, e a plataforma hoje funciona como descrito no resto deste manual.
## Cartões virtuais
Os cartões virtuais são criados na hora pela API. Os dados do cartão (número, validade, CVV) chegam ao portador por um elemento seguro embutido no seu app ou site, então os dados sensíveis nunca passam pelos seus servidores e o seu escopo de PCI DSS fica mínimo.
Os cartões virtuais já podem ser adicionados ao Apple Pay e ao Google Pay.
## Cartões físicos
Os cartões físicos são produzidos com a arte do seu programa e enviados aos portadores no mundo todo. Um cartão físico começa como um pedido (veja [Pedir cartões físicos](https://docs.web3card.dev/pt-BR/guides/order-physical-cards/)) e precisa ser ativado pelo portador antes do primeiro uso.
## Situações do cartão
| Situação | Significado |
| --- | --- |
| `pending` | Criado, esperando a ativação (físico) ou a liberação (virtual) |
| `active` | Pronto para usar |
| `frozen` | Bloqueado por um tempo, pelo portador ou pelo seu programa |
| `lost` | Comunicado como perdido; bloqueado de vez |
| `stolen` | Comunicado como roubado; bloqueado de vez |
| `voided` | Cartão virtual cancelado |
As mudanças de situação estão na [API de cartões](https://docs.web3card.dev/pt-BR/api-reference/cards/). `frozen` volta atrás; `lost`, `stolen` e `voided` são definitivas, e um cartão substituto pode ser criado com o mesmo cofre.
## Controles de gasto
Cada cartão tem um limite diário de gasto, conferido no momento da autorização. O limite pode ser lido e alterado pela API, e a mudança vale na hora:
- `GET /cards/{id}/limits`
- `PUT /cards/{id}/limits`
## Um cartão, um cofre
Cada cartão liquida contra o seu próprio cofre multisig individual. É essa relação de um para um que mantém o programa não custodial: congelar um cartão nunca trava o dinheiro do usuário, e o usuário pode sacar do cofre quando quiser. Veja [Cofres](https://docs.web3card.dev/pt-BR/concepts/vaults/).
---
Source: https://docs.web3card.dev/pt-BR/concepts/vaults/
# Cofres
O cofre é o coração do desenho não custodial da Web3Card. Cada cartão tem por trás o seu próprio cofre multisig em contrato inteligente, implantado na rede escolhida pelo portador.
**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](https://docs.web3card.dev/pt-BR/api/overview/) a substitui, e a plataforma hoje funciona como descrito no resto deste manual.
## Como o cofre funciona
- **Individual.** Um cofre por cartão. O dinheiro nunca é misturado com o de outros usuários nem com o do operador do programa.
- **Do usuário.** A carteira do portador é a dona do cofre. O operador de liquidação da Web3Card é um cossignatário autorizado só a executar as liquidações dos pagamentos que o usuário fez com o cartão.
- **Transparente.** O cofre é um contrato numa rede pública. Cada liquidação é uma transação verificável na rede.
## O que o cofre guarda
O cofre guarda o saldo disponível do cartão na moeda de liquidação do programa e, se as recargas com token estiverem ligadas, também o token do seu projeto (veja [Redes e tokens](https://docs.web3card.dev/pt-BR/concepts/chains-and-tokens/)).
## Liquidação
Quando o portador paga com o cartão, o pagamento é autorizado na hora contra o saldo do cofre. Depois, a liquidação leva o valor autorizado do cofre, pelo operador de liquidação, até o banco emissor, como uma liquidação padrão da Visa. O caminho inteiro está no [ciclo da transação](https://docs.web3card.dev/pt-BR/concepts/transaction-lifecycle/).
## Saques
O portador pode sacar do cofre quando quiser, assinando o saque com a carteira dona:
- `POST /vaults/{id}/withdrawals`: prepara os dados da transação de saque
- O usuário assina e envia com a própria carteira
O valor disponível para saque só diminui pelo que já foi autorizado e ainda não liquidado.
## Limites de gasto na rede
O contrato do cofre repete os limites diários do cartão, como uma segunda camada de proteção: mesmo um caminho de autorização comprometido não consegue liquidar mais do que o limite da rede permite.
## API de cofres
Os endereços de implantação, configuração, saldo e saque estão na [referência da API de cofres](https://docs.web3card.dev/pt-BR/api-reference/vaults/).
---
Source: https://docs.web3card.dev/pt-BR/concepts/chains-and-tokens/
# Redes e tokens
A Web3Card é multirrede. Cada usuário escolhe a rede em que o cofre dele fica, e cada programa define quais tokens aceita nas recargas.
**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](https://docs.web3card.dev/pt-BR/api/overview/) a substitui, e a plataforma hoje funciona como descrito no resto deste manual.
## Redes aceitas
| Rede | Identificador | Cofres | Observação |
| --- | --- | --- | --- |
| Ethereum | `ethereum` | ✓ | Mainnet |
| Polygon | `polygon` | ✓ | PoS |
| Arbitrum | `arbitrum` | ✓ | Arbitrum One |
| BNB Chain | `bnb` | ✓ | BSC |
Outras redes entram programa a programa. Fale com o seu gerente de integração sobre redes que não estão na lista.
## Moedas de liquidação
As autorizações do cartão liquidam em stablecoins:
| Token | Identificador | Redes |
| --- | --- | --- |
| USDC | `USDC` | Todas as redes aceitas |
| USDT | `USDT` | Todas as redes aceitas |
A moeda de liquidação do programa é definida em cada cofre, na implantação (campo `currency`).
## Tokens de projeto
O programa pode aceitar recargas com o próprio token. Quando o usuário recarrega com o token do projeto, a plataforma o converte na moeda de liquidação do cofre, pelo preço de mercado do momento, e credita o cofre com o saldo em stablecoin resultante.
Isso dá ao seu token uma utilidade concreta, do dia a dia: ele vira um jeito de carregar um cartão que funciona em qualquer lugar.
```json
{
"topUp": {
"token": "YOURTOKEN",
"amountIn": "1500.00",
"converted": { "currency": "USDC", "amountOut": "487.35" },
"rate": "0.32490",
"chain": "polygon"
}
}
```
A disponibilidade das recargas com token, os pares e os locais de conversão são definidos na entrada do programa.
---
Source: https://docs.web3card.dev/pt-BR/concepts/transaction-lifecycle/
# Ciclo da transação
Todo pagamento com o cartão faz o mesmo caminho, da maquininha até a liquidação na rede. Entender esse ciclo ajuda a montar saldos e extratos certos.
**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](https://docs.web3card.dev/pt-BR/api/overview/) a substitui, e a plataforma hoje funciona como descrito no resto deste manual.
## Etapas
```
Authorization → Clearing → Settlement (on-chain)
```
### 1. Autorização
O portador aproxima ou digita o cartão. A Visa leva o pedido de autorização até a Web3Card, que confere na hora:
- A situação do cartão é `active`
- O valor está dentro do limite diário do cartão
- O saldo do cofre cobre o valor
Se tudo passa, o valor fica reservado e o lojista recebe a aprovação, normalmente em menos de um segundo. A transação aparece com a situação `pending`.
### 2. Compensação
O lojista envia a captura final (em geral em horas, até alguns dias em hotéis e parecidos). O valor capturado substitui a reserva; pequenas diferenças (gorjeta, ajuste de câmbio) são normais.
### 3. Liquidação
O valor capturado é liquidado a partir do cofre do usuário: o operador de liquidação cossigna uma transferência para fora do cofre, e o dinheiro segue até o banco emissor como liquidação padrão da Visa. A transação passa a `settled`, e o hash da transferência na rede fica anexado ao registro.
## Situações da transação
| Situação | Significado |
| --- | --- |
| `pending` | Autorizada, valor reservado |
| `settled` | Compensada e liquidada na rede |
| `declined` | Autorização recusada (limite, saldo, situação do cartão) |
| `reversed` | Autorização liberada sem captura |
| `refunded` | Estorno do lojista devolvido ao cofre |
| `disputed` | Contestação em andamento |
## Estornos e disputas
Os estornos chegam ao cofre como transações de crédito separadas. As disputas podem ser abertas pela API em até 60 dias depois da liquidação; veja a [API de transações](https://docs.web3card.dev/pt-BR/api-reference/transactions/).
## Eventos na hora
Cada mudança de situação gera um webhook (`transaction.created`, `transaction.updated`), para o seu app mostrar os pagamentos ao vivo. Veja [Webhooks](https://docs.web3card.dev/pt-BR/guides/webhooks/).
---
Source: https://docs.web3card.dev/pt-BR/guides/create-virtual-cards/
# Criar cartões virtuais
Os cartões virtuais são criados na hora e ficam prontos para compras on-line e para as carteiras digitais (Apple Pay / Google Pay) assim que o cofre por trás deles tem saldo.
**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](https://docs.web3card.dev/pt-BR/api/overview/) a substitui, e a plataforma hoje funciona como descrito no resto deste manual.
## Antes de começar
- Usuário criado e e-mail confirmado
- KYC aprovado (webhook `kyc.approved` recebido)
- Cofre do usuário implantado
## Crie o cartão
```bash
curl -X POST https://api.web3card.dev/v1/cards \
-H "Authorization: Bearer w3c_live_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{ "userId": "usr_9f4c", "type": "virtual" }'
```
```json
{
"id": "card_3b7c",
"userId": "usr_9f4c",
"type": "virtual",
"status": "active",
"last4": "1234",
"network": "visa",
"vaultId": "vlt_77aa",
"createdAt": "2026-07-19T14:00:00Z"
}
```
## Mostre os dados do cartão com segurança
A API nunca devolve os dados completos do cartão. Para mostrar número, validade e CVV ao portador, embuta o **elemento seguro**: um iframe hospedado, compatível com PCI, preso a um cartão e a uma sessão.
```bash
curl -X POST https://api.web3card.dev/v1/cards/card_3b7c/secure-session \
-H "Authorization: Bearer w3c_live_xxxxxxxxxxxxxxxx"
```
```json
{ "url": "https://secure.web3card.dev/e/card_3b7c?st=abc123", "expiresIn": 300 }
```
Mostre o endereço devolvido num iframe dentro do seu app. A sessão vale uma vez e expira em cinco minutos.
## Carteiras digitais
O portador pode adicionar o cartão virtual ao Apple Pay e ao Google Pay direto pela tela do elemento seguro, ou o seu app pode fazer isso por código, se estiver cadastrado nas carteiras.
## Congelar e anular
```bash
# Freeze (reversible)
curl -X POST https://api.web3card.dev/v1/cards/card_3b7c/freeze \
-H "Authorization: Bearer w3c_live_xxxxxxxxxxxxxxxx"
# Void (terminal)
curl -X POST https://api.web3card.dev/v1/cards/card_3b7c/void \
-H "Authorization: Bearer w3c_live_xxxxxxxxxxxxxxxx"
```
Anular um cartão não mexe no cofre: o saldo do usuário fica intacto e um cartão novo pode ser criado com o mesmo cofre.
---
Source: https://docs.web3card.dev/pt-BR/guides/order-physical-cards/
# Pedir cartões físicos
Os cartões físicos levam a arte do seu programa e são enviados para o mundo todo. O pedido segue uma pequena sequência de situações: você cria o pedido, ele é produzido e enviado, e o portador ativa o cartão quando recebe.
**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](https://docs.web3card.dev/pt-BR/api/overview/) a substitui, e a plataforma hoje funciona como descrito no resto deste manual.
## Situações do pedido
```
created → confirmed → in_production → shipped → delivered → activated
```
O pedido pode ser cancelado enquanto está em `created` ou `confirmed`. Depois de `in_production`, não dá mais para cancelar.
## Crie o pedido
```bash
curl -X POST https://api.web3card.dev/v1/card-orders \
-H "Authorization: Bearer w3c_live_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"userId": "usr_9f4c",
"shippingAddress": {
"line1": "Av. Paulista 1000",
"city": "Sao Paulo",
"state": "SP",
"postalCode": "01310-100",
"country": "BR"
}
}'
```
```json
{
"id": "ord_51de",
"userId": "usr_9f4c",
"status": "created",
"estimatedDelivery": "2026-08-04",
"createdAt": "2026-07-19T14:00:00Z"
}
```
## Acompanhe o pedido
```bash
curl https://api.web3card.dev/v1/card-orders/ord_51de \
-H "Authorization: Bearer w3c_live_xxxxxxxxxxxxxxxx"
```
As mudanças de situação do pedido também chegam pelo webhook `card_order.updated`, com o código de rastreio da transportadora depois do envio.
## Ativação
Ao receber, o portador ativa o cartão confirmando os quatro últimos dígitos e criando uma senha (PIN), no seu app pela API ou na tela do elemento seguro:
```bash
curl -X POST https://api.web3card.dev/v1/cards/card_8a1f/activate \
-H "Authorization: Bearer w3c_live_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{ "last4": "5678" }'
```
O cartão físico liquida contra o mesmo cofre do cartão virtual do usuário, com o mesmo saldo e os mesmos limites.
---
Source: https://docs.web3card.dev/pt-BR/guides/top-ups/
# Recargas
O cartão pode gastar enquanto o cofre dele tem saldo. O usuário recarrega transferindo tokens aceitos para o endereço do cofre; não é preciso chamar a API para receber, mas a API traz tudo o que você precisa para uma boa experiência de recarga.
**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](https://docs.web3card.dev/pt-BR/api/overview/) a substitui, e a plataforma hoje funciona como descrito no resto deste manual.
## Pegue o endereço de depósito
O endereço do cofre é o endereço de depósito. Mostre-o (com um QR code) no seu app:
```bash
curl https://api.web3card.dev/v1/vaults/vlt_77aa \
-H "Authorization: Bearer w3c_live_xxxxxxxxxxxxxxxx"
```
```json
{
"id": "vlt_77aa",
"userId": "usr_9f4c",
"chain": "polygon",
"address": "0x8247E5a9c11b36c1d19D4a2e9Eb0cE3606eB48a3",
"currency": "USDC",
"balance": "487.35",
"status": "active"
}
```
O depósito precisa ser feito na rede do cofre. Tokens enviados em outra rede não são creditados sozinhos; recuperar exige intervenção manual do suporte.
## Recargas com stablecoin
As transferências na moeda de liquidação do cofre (USDC ou USDT) são creditadas assim que a transferência fica definitiva na rede do cofre. Um webhook `vault.credited` sai com o valor e o hash da transação.
## Recargas com o token do projeto
Se o seu programa aceita recarga com token, as transferências do token do seu projeto para o cofre são convertidas na moeda de liquidação pelo preço de mercado e creditadas como saldo em stablecoin. Os detalhes da conversão vêm no evento do webhook:
```json
{
"type": "vault.credited",
"data": {
"vaultId": "vlt_77aa",
"source": "token_conversion",
"tokenIn": "YOURTOKEN",
"amountIn": "1500.00",
"currency": "USDC",
"amountCredited": "487.35",
"rate": "0.32490",
"txHash": "0x9c2f…e11a"
}
}
```
## Mostrar o saldo
Use `GET /vaults/{id}` para o saldo oficial. O campo `balance` já desconta o que está reservado por autorizações pendentes, então pode ser mostrado como "disponível para gastar".
---
Source: https://docs.web3card.dev/pt-BR/guides/webhooks/
# Webhooks
Os webhooks levam os eventos ao seu backend na hora: transações, resultados de KYC, créditos no cofre, mudanças de situação de cartões e pedidos. Eles são a base de uma experiência de cartão que responde rápido.
**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](https://docs.web3card.dev/pt-BR/api/overview/) a substitui, e a plataforma hoje funciona como descrito no resto deste manual.
## Assine
Cadastre o seu endereço e escolha os eventos que quer receber:
```bash
curl -X POST https://api.web3card.dev/v1/webhooks \
-H "Authorization: Bearer w3c_live_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"url": "https://api.yourproject.com/hooks/web3card",
"events": ["transaction.*", "kyc.*", "vault.credited", "card_order.updated"]
}'
```
```json
{ "id": "wh_2210", "status": "active", "secret": "whsec_9k3j…" }
```
## Confira as assinaturas
Toda entrega é assinada. Calcule um HMAC SHA-256 do corpo bruto com o segredo do seu webhook e compare com o cabeçalho `X-W3C-Signature`:
```js
const crypto = require("crypto");
function verify(rawBody, signature, secret) {
const expected = crypto
.createHmac("sha256", secret)
.update(rawBody)
.digest("hex");
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expected)
);
}
```
Recuse toda entrega cuja assinatura não bata.
## Catálogo de eventos
| Evento | Sai quando |
| --- | --- |
| `transaction.created` | Uma autorização nova é aprovada ou recusada |
| `transaction.updated` | Uma transação muda de situação (liquidada, estornada, contestada…) |
| `vault.credited` | Uma recarga é creditada num cofre |
| `vault.debited` | Uma liquidação ou um saque sai de um cofre |
| `kyc.approved` | Verificação de identidade aprovada |
| `kyc.rejected` | Verificação de identidade recusada |
| `card.updated` | Mudança de situação do cartão (congelado, perdido, anulado…) |
| `card_order.updated` | O pedido de cartão físico avança |
## Entrega e novas tentativas
As entregas esperam uma resposta `2xx` em até 10 segundos. As que falham são repetidas com intervalo crescente por até 24 horas. Cada evento chega pelo menos uma vez; use o `id` do evento para não processar duas vezes.
---
Source: https://docs.web3card.dev/pt-BR/api-reference/overview/
# Referência da API
A API da Web3Card é uma API REST sobre HTTPS, com corpo de pedido e de resposta em JSON.
**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](https://docs.web3card.dev/pt-BR/api/overview/) a substitui, e a plataforma hoje funciona como descrito no resto deste manual.
## URL base
```
https://api.web3card.dev/v1
```
## Autenticação
Todos os endereços de parceiro pedem a sua chave de API como token Bearer:
```
Authorization: Bearer w3c_live_xxxxxxxxxxxxxxxx
```
As sessões do usuário final (para ações assinadas pela carteira do portador) usam o Sign-In with Ethereum por cima da chave de parceiro. Veja [Autenticação](https://docs.web3card.dev/pt-BR/api-reference/authentication/).
## Ambientes
| Ambiente | Prefixo da chave | Comportamento |
| --- | --- | --- |
| Produção | `w3c_live_` | Cartões de verdade, cofres na mainnet |
| Sandbox | `w3c_test_` | Cartões de teste, cofres em testnet, autorizações simuladas |
## Erros
Os erros usam os códigos HTTP de costume e um corpo sempre igual:
```json
{
"error": {
"code": "insufficient_balance",
"message": "Vault balance does not cover the requested amount.",
"requestId": "req_b81f2c"
}
}
```
| Código | Significado |
| --- | --- |
| `400` | Corpo ou parâmetros inválidos |
| `401` | Chave de API ausente ou inválida |
| `403` | Chave válida, mas sem permissão para este recurso |
| `404` | Recurso não encontrado |
| `409` | Conflito com a situação do recurso (ex.: ativar um cartão anulado) |
| `429` | Limite de chamadas atingido |
| `5xx` | Erro da plataforma; pode repetir com intervalo crescente |
Mande o `requestId` quando falar com o suporte sobre uma chamada específica.
## Paginação
Os endereços de lista devolvem páginas com um cursor opaco:
```
GET /transactions?limit=50&cursor=eyJvZmZzZXQiOjUwfQ
```
```json
{ "data": [ … ], "nextCursor": "eyJvZmZzZXQiOjEwMH0" }
```
`nextCursor` vem `null` na última página.
## Idempotência
Mande o cabeçalho `Idempotency-Key` em todo `POST` que você possa repetir. Duas chamadas com a mesma chave devolvem o mesmo resultado e criam no máximo um recurso.
---
Source: https://docs.web3card.dev/pt-BR/api-reference/authentication/
# Autenticação
Duas camadas de autenticação cobrem os dois tipos de quem chama:
1. **Autenticação do parceiro:** o seu backend, com uma chave de API.
2. **Autenticação do usuário:** o portador, com a carteira dele (Sign-In with Ethereum), para as ações que precisam da assinatura do dono do cofre.
**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](https://docs.web3card.dev/pt-BR/api/overview/) a substitui, e a plataforma hoje funciona como descrito no resto deste manual.
## Chaves de API do parceiro
As chaves são entregues por ambiente, na entrada do programa, e enviadas como token Bearer:
```bash
curl https://api.web3card.dev/v1/users \
-H "Authorization: Bearer w3c_live_xxxxxxxxxxxxxxxx"
```
As chaves podem ser trocadas a qualquer momento no painel do parceiro. A chave antiga continua valendo por 24 horas depois da troca.
## Sign-In with Ethereum (SIWE)
As ações do dono do cofre (saques, incluir carteiras, mudar limites na rede) pedem uma sessão do usuário, provada por uma assinatura da carteira.
### POST /auth/nonce
Gera a mensagem que o usuário precisa assinar.
```json
// Request
{ "walletAddress": "0x71C2a4f3b7c48d19D4a2e9Eb0cE3606eB48a3a4F" }
// Response
{
"nonce": "kX9m2pQr",
"message": "web3card.dev wants you to sign in with your Ethereum account…"
}
```
### POST /auth/verify
Confere a assinatura SIWE e abre uma sessão do usuário.
```json
// Request
{
"walletAddress": "0x71C2a4f3b7c48d19D4a2e9Eb0cE3606eB48a3a4F",
"signature": "0x8b4d…c91e"
}
// Response
{ "sessionToken": "w3cs_a91k…", "expiresIn": 3600 }
```
Mande o token da sessão junto com a sua chave de API nos endereços assinados pelo usuário:
```
Authorization: Bearer w3c_live_xxxxxxxxxxxxxxxx
X-W3C-User-Session: w3cs_a91k…
```
## Confirmação do e-mail
### POST /users/\{id\}/email/otp
Envia um código de uso único para o e-mail do usuário.
### POST /users/\{id\}/email/verify
```json
// Request
{ "code": "482913" }
// Response
{ "verified": true }
```
---
Source: https://docs.web3card.dev/pt-BR/api-reference/users-and-kyc/
# 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](https://docs.web3card.dev/pt-BR/api/overview/) a substitui, e a plataforma hoje funciona como descrito no resto deste manual.
## POST /users
Cria um usuário.
```json
// Request
{
"email": "ana@example.com",
"walletAddress": "0x71C2a4f3b7c48d19D4a2e9Eb0cE3606eB48a3a4F",
"chain": "polygon"
}
// Response
{
"id": "usr_9f4c",
"email": "ana@example.com",
"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:
```json
// 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
---
Source: https://docs.web3card.dev/pt-BR/api-reference/cards/
# API de cartões
Crie e gerencie os cartões do seu programa. As situações e o ciclo de vida estão em [Cartões](https://docs.web3card.dev/pt-BR/concepts/cards/).
**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](https://docs.web3card.dev/pt-BR/api/overview/) a substitui, e a plataforma hoje funciona como descrito no resto deste manual.
## POST /cards
Cria um cartão virtual para um usuário com cofre ativo.
```json
// Request
{ "userId": "usr_9f4c", "type": "virtual" }
// Response
{
"id": "card_3b7c",
"userId": "usr_9f4c",
"vaultId": "vlt_77aa",
"type": "virtual",
"status": "active",
"last4": "1234",
"network": "visa",
"createdAt": "2026-07-19T14:00:00Z"
}
```
## GET /cards
Lista os cartões. Filtros: `userId`, `status`, `type`.
## GET /cards/\{id\}
Consulta um cartão e a situação dele.
## POST /cards/\{id\}/activate
Ativa um cartão físico entregue.
```json
// Request
{ "last4": "5678" }
```
## POST /cards/\{id\}/freeze
Bloqueia as autorizações por um tempo. Volta atrás.
## POST /cards/\{id\}/unfreeze
Tira o congelamento e devolve o cartão a `active`.
## POST /cards/\{id\}/report-lost
Bloqueia de vez um cartão comunicado como perdido. Definitivo.
## POST /cards/\{id\}/report-stolen
Bloqueia de vez um cartão comunicado como roubado. Definitivo.
## POST /cards/\{id\}/void
Cancela um cartão virtual. Definitivo. O cofre e o saldo dele não mudam.
## GET /cards/\{id\}/limits
```json
// Response
{ "daily": { "amount": "1000.00", "currency": "USDC", "spentToday": "112.40" } }
```
## PUT /cards/\{id\}/limits
Define o limite diário. Pede uma sessão do usuário (assinada pelo dono do cofre).
```json
// Request
{ "daily": { "amount": "2500.00" } }
```
## POST /cards/\{id\}/secure-session
Cria uma sessão de uso único do elemento seguro, para mostrar os dados completos do cartão ao portador. Veja [Criar cartões virtuais](https://docs.web3card.dev/pt-BR/guides/create-virtual-cards/).
---
Source: https://docs.web3card.dev/pt-BR/api-reference/vaults/
# API de cofres
Implante e gerencie os cofres multisig em contrato inteligente que ficam por trás de cada cartão. Veja [Cofres](https://docs.web3card.dev/pt-BR/concepts/vaults/).
**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](https://docs.web3card.dev/pt-BR/api/overview/) a substitui, e a plataforma hoje funciona como descrito no resto deste manual.
## POST /vaults
Implanta um cofre para um usuário com KYC aprovado.
```json
// Request
{ "userId": "usr_9f4c", "chain": "polygon", "currency": "USDC" }
// Response
{
"id": "vlt_77aa",
"userId": "usr_9f4c",
"chain": "polygon",
"currency": "USDC",
"address": null,
"status": "deploying",
"createdAt": "2026-07-19T14:00:00Z"
}
```
A implantação é assíncrona. O cofre passa a `active` quando o contrato está no ar, e o campo `address` é preenchido. Sai um webhook `vault.deployed`.
## GET /vaults/\{id\}
Consulta um cofre: endereço, situação e saldo disponível.
```json
// Response
{
"id": "vlt_77aa",
"userId": "usr_9f4c",
"chain": "polygon",
"currency": "USDC",
"address": "0x8247E5a9c11b36c1d19D4a2e9Eb0cE3606eB48a3",
"balance": "487.35",
"status": "active"
}
```
`balance` é o valor que pode ser gasto: o saldo na rede menos as reservas de autorizações pendentes.
## GET /vaults
Lista os cofres. Filtros: `userId`, `chain`, `status`.
## GET /vaults/\{id\}/owners
Lista as carteiras donas do cofre.
## POST /vaults/\{id\}/owners
Inclui uma carteira dona. Pede uma sessão do usuário; devolve os dados tipados EIP-712 para o dono atual assinar.
## DELETE /vaults/\{id\}/owners/\{address\}
Tira uma carteira dona. Pede uma sessão do usuário e a assinatura do dono.
## POST /vaults/\{id\}/withdrawals
Prepara um saque do cofre para a carteira do dono. Devolve os dados da transação para o dono assinar e enviar com a própria carteira.
```json
// Request
{ "amount": "200.00", "to": "0x71C2a4f3b7c48d19D4a2e9Eb0cE3606eB48a3a4F" }
// Response
{
"to": "0x8247E5a9c11b36c1d19D4a2e9Eb0cE3606eB48a3",
"data": "0xa9059cbb…",
"value": "0",
"chainId": 137
}
```
O saque nunca depende de aprovação da plataforma: o dono do cofre sempre pode sair com o próprio dinheiro.
---
Source: https://docs.web3card.dev/pt-BR/api-reference/transactions/
# API de transações
Leia os pagamentos feitos com os cartões do seu programa. As situações e as etapas estão em [Ciclo da transação](https://docs.web3card.dev/pt-BR/concepts/transaction-lifecycle/).
**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](https://docs.web3card.dev/pt-BR/api/overview/) a substitui, e a plataforma hoje funciona como descrito no resto deste manual.
## GET /transactions
Lista as transações do programa inteiro. Filtros: `userId`, `cardId`, `status`, `from`, `to`. Paginada com `limit` e `cursor`.
```json
// Response
{
"data": [
{
"id": "txn_c410",
"cardId": "card_3b7c",
"userId": "usr_9f4c",
"status": "settled",
"amount": "42.90",
"currency": "USDC",
"merchant": {
"name": "AIRLINE TICKETS LTD",
"category": "airlines",
"country": "US"
},
"authorizedAt": "2026-07-18T09:12:44Z",
"settledAt": "2026-07-19T02:03:10Z",
"settlementTxHash": "0x9c2f…e11a"
}
],
"nextCursor": null
}
```
`settlementTxHash` liga cada pagamento liquidado à liquidação verificável na rede.
## GET /transactions/\{id\}
Consulta uma transação, com o histórico completo de eventos (autorização, captura, liquidação, estornos).
## GET /transactions/dispute-reasons
Lista os códigos de motivo de disputa aceitos.
```json
// Response
{
"data": [
{ "code": "fraud", "label": "Unauthorized transaction" },
{ "code": "not_received", "label": "Goods or services not received" },
{ "code": "duplicate", "label": "Duplicate charge" },
{ "code": "amount_differs", "label": "Charged amount differs" }
]
}
```
## POST /transactions/\{id\}/disputes
Abre uma disputa sobre uma transação liquidada. Vale até 60 dias depois da liquidação.
```json
// Request
{ "reason": "duplicate", "comment": "Charged twice for the same order." }
// Response
{ "id": "dsp_11ba", "transactionId": "txn_c410", "status": "open" }
```
O andamento da disputa chega pelos webhooks `transaction.updated`, com o objeto `dispute` dentro.
---
Source: https://docs.web3card.dev/pt-BR/api-reference/webhooks/
# API de webhooks
Gerencie as assinaturas de webhook do seu programa. A conferência de assinatura, as novas tentativas e o catálogo completo de eventos estão no [guia de webhooks](https://docs.web3card.dev/pt-BR/guides/webhooks/).
**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](https://docs.web3card.dev/pt-BR/api/overview/) a substitui, e a plataforma hoje funciona como descrito no resto deste manual.
## POST /webhooks
Cria uma assinatura.
```json
// Request
{
"url": "https://api.yourproject.com/hooks/web3card",
"events": ["transaction.*", "kyc.*", "vault.credited"]
}
// Response
{
"id": "wh_2210",
"url": "https://api.yourproject.com/hooks/web3card",
"events": ["transaction.*", "kyc.*", "vault.credited"],
"status": "active",
"secret": "whsec_9k3j…"
}
```
O `secret` só vem na criação. Guarde com segurança; ele assina cada entrega.
## GET /webhooks
Lista as suas assinaturas.
## GET /webhooks/\{id\}
Consulta uma assinatura e os números recentes de entrega.
## PATCH /webhooks/\{id\}
Altera o endereço ou os eventos escolhidos.
## DELETE /webhooks/\{id\}
Apaga uma assinatura. As novas tentativas pendentes são canceladas.
## POST /webhooks/\{id\}/rotate-secret
Troca o segredo de assinatura. O segredo antigo continua valendo por uma hora, para a troca acontecer sem parada.
## POST /webhooks/\{id\}/test
Envia um evento `ping` assinado para o seu endereço, para conferir a conexão de ponta a ponta.
```json
// Response
{ "delivered": true, "responseStatus": 200, "latencyMs": 184 }
```
## Formato da entrega
```json
{
"id": "evt_88d1",
"type": "transaction.created",
"createdAt": "2026-07-19T14:00:00Z",
"data": { … }
}
```
Cabeçalhos de toda entrega:
| Cabeçalho | Conteúdo |
| --- | --- |
| `X-W3C-Signature` | HMAC SHA-256 do corpo bruto |
| `X-W3C-Event-Id` | Id do evento, para não processar duas vezes |
| `X-W3C-Event-Type` | Tipo do evento |
---
Source: https://docs.web3card.dev/pt-BR/glossary/
# Glossário
Os termos usados nesta documentação, em ordem alfabética.
## Aplicativo autenticador
Um aplicativo no celular que mostra um código de 6 dígitos, trocado a cada 30 segundos. Google Authenticator, Microsoft Authenticator, Authy e 1Password são exemplos. Todo login na plataforma pede esse código. Também chamado de autenticação em dois fatores, ou 2FA.
## App Pessoal
O lado da plataforma usado pelos usuários finais. Cada empresa tem o seu, no próprio domínio e com a própria marca. Veja [Como a plataforma funciona](https://docs.web3card.dev/pt-BR/platform/overview/).
## CNAME
Um registro no DNS de um domínio que aponta um endereço para outro. A empresa cria um CNAME para ligar o seu subdomínio à plataforma. Veja [O seu domínio](https://docs.web3card.dev/pt-BR/platform/white-label/#your-own-domain).
## Dono
A pessoa que criou a empresa no painel Business. Convidar a equipe vai ser tarefa do dono.
## Empresa
O negócio que usa a Web3Card para operar um programa de cartões. Na plataforma, a empresa tem um dono, uma equipe, uma marca e os seus próprios usuários.
## Instituição parceira
Uma instituição financeira licenciada e regulada, dentro da rede Visa. As instituições parceiras emitem os cartões. A Web3Card fornece o software.
## KYB
Know Your Business, ou conheça a sua empresa. É a verificação de uma empresa: quem são os donos, onde ela está registrada e o que ela faz.
## KYC
Know Your Customer, ou conheça o seu cliente. É a verificação da identidade de uma pessoa, exigida antes de o cartão poder ser usado.
## Membro
A pessoa que entra na equipe de uma empresa no painel Business por convite do dono.
## Painel Business
O lado da plataforma usado pela empresa que opera um programa de cartões e pela equipe dela. Tem um endereço só para todas as empresas: `business.web3card.dev`. Veja [Como a plataforma funciona](https://docs.web3card.dev/pt-BR/platform/overview/).
## Programa de cartões
O conjunto de cartões que uma empresa oferece aos seus usuários, com as suas regras, a sua marca e a instituição parceira que emite os cartões.
## Sessão
O período em que você fica conectado em um aparelho. Dura 1 dia, ou 7 dias quando você escolhe **Stay signed in for 7 days**. Termina antes quando você sai, quando a senha ou o autenticador mudam, ou quando a plataforma é atualizada. Veja [Entrar e sair](https://docs.web3card.dev/pt-BR/access/sign-in/).
## Stablecoin
Uma moeda digital feita para manter o valor de uma moeda tradicional. Os cartões da plataforma são recarregados com stablecoins de dólar, como USDC e USDT.
## Tema
O conjunto de cores do app. São quatro: Graphite Dark, Graphite Light, Gold Dark e Ivory. A empresa escolhe um como padrão para os seus usuários, e cada pessoa pode escolher outro no próprio aparelho. Veja [White-label](https://docs.web3card.dev/pt-BR/platform/white-label/).
## Usuário final
A pessoa que tem e usa o cartão. O usuário final se cadastra no app Pessoal de uma empresa.
## White-label
Software fornecido por uma empresa e apresentado com a marca de outra. Na Web3Card, os seus usuários veem o seu nome, o seu logo e o seu domínio. Veja [White-label](https://docs.web3card.dev/pt-BR/platform/white-label/).