API de cartão virtual: como automatizar a emissão de cartões com código

Para que serve uma API de emissão de cartões

Emitir meia dúzia de cartões à mão é tranquilo. Emitir um cartão para cada novo cliente, campanha ou fornecedor, e manter cada um com saldo, logo vira trabalho repetitivo. Uma API de emissão de cartões transforma esses passos em código:

• Crie um cartão por entidade automaticamente, por exemplo quando um novo cliente se cadastra no seu CRM.
• Recarregue cartões em horários programados ou quando o saldo cair.
• Congele cartões na hora quando um orçamento é atingido ou um contrato termina.
• Sincronize transações com suas ferramentas de contabilidade ou relatórios.
• Reaja a eventos em tempo real via webhooks, em vez de ficar consultando.

A API faz o que o painel faz, a partir do seu servidor. Cada cartão emitido e cada carga feita são pagos com o saldo da sua conta, que você abastece com depósitos em cripto e que fica sempre em USDT.

Como obter acesso à API de cartão virtual

O acesso leva três passos:

1. Crie uma chave. Abra o acesso à API no painel e gere uma chave. As chaves começam com sk_live_.
2. Peça a ativação. Confirme seu e-mail e faça um primeiro depósito; depois peça ao suporte (por um ticket no painel) para ativar a API na sua conta.
3. Faça uma chamada. Consulte seu saldo e emita seu primeiro cartão.

Enquanto a conta não estiver pronta, uma chave válida recebe resposta 403. Você verá o código de erro onboarding_incomplete até confirmar o e-mail e fazer um primeiro depósito, e depois api_not_enabled até o acesso à API ser ativado.

Não existe ambiente sandbox separado nem pacotes de SDK oficiais. Você chama a API REST diretamente com qualquer cliente HTTP, o que simplifica a integração, mas significa que toda chamada é real. Teste com valores pequenos.

Básico: URL base, autenticação e formato

• URL base: https://usdtcryptocard.com/api/v1
• Autenticação: envie sua chave como Bearer token no cabeçalho Authorization de toda requisição.
• Formato: JSON via HTTPS. Valores em dólares americanos com duas casas decimais. Datas em ISO 8601, em UTC.
• Paginação: os endpoints de listagem aceitam page e per_page.

Mantenha a chave no seu servidor. Quem tiver a chave pode movimentar o dinheiro da sua conta, então carregue-a de uma variável de ambiente e nunca a inclua em código de navegador ou de app.

Sua primeira chamada

Consultar o saldo é uma primeira requisição segura:

curl https://usdtcryptocard.com/api/v1/wallet/balance \
  -H "Authorization: Bearer sk_live_..."

A resposta mostra seu saldo em USDT, os depósitos pendentes e o que está nos seus cartões:

{
  "balance": 1312.5,
  "currency": "USDT",
  "pending_deposits": 500.0,
  "cards_active": 8,
  "cards_total_balance": 2450.0
}

Os endpoints

A API tem 15 endpoints distribuídos em seis recursos.

Parâmetros completos e exemplos de resposta estão na referência da API.

Emitindo um cartão por código

Criar um cartão escolhe um BIN e carrega o cartão a partir do seu saldo na mesma requisição. Os campos são:

• bin_id (obrigatório): o BIN em que o cartão será emitido. Liste as opções com GET /bins.
• amount (obrigatório): a carga inicial em USD, retirada do seu saldo. O mínimo é $50, e a taxa de emissão de $1 é cobrada à parte.
• label: um nome seu para o cartão.
• spending_limit: um limite de gastos em USD.
• allowed_categories: categorias de estabelecimento em que o cartão pode ser usado, como publicidade ou software. Qualquer outra é recusada.
• auto_freeze_at: congela o cartão automaticamente quando o saldo cair abaixo desse valor.
• metadata: pares chave-valor para o seu próprio controle.

Veja a mesma requisição em Node.js:

const res = await fetch('https://usdtcryptocard.com/api/v1/cards', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.USDTCC_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    bin_id: '491653',
    amount: 500,
    label: 'Meta Ads - Campaign 12',
    spending_limit: 2000,
    allowed_categories: ['advertising'],
    metadata: { campaign: 'fall_2026' },
  }),
});
const card = await res.json();

Uma chamada bem-sucedida retorna 201 com o objeto do cartão: id, BIN, bandeira, últimos quatro dígitos, status, saldo, além do seu label e metadata. O resumo omite de propósito o número completo e o CVV.

Obtendo o número do cartão com segurança

GET /cards/{card_id}/details retorna o número completo, o CVV e a validade. Trate isso como dado sensível: nunca registre a resposta em log nem a armazene sem criptografia, e só a busque quando realmente precisar passar os dados para uma pessoa ou um checkout. Esse endpoint tem limite de requisições mais apertado que os demais.

Carregar, congelar e encerrar

• Recarregar: POST /cards/{card_id}/fund com um amount move dinheiro do seu saldo para o cartão. O valor fica disponível na hora.
• Retirar fundos: POST /cards/{card_id}/withdraw devolve o saldo do cartão para a sua carteira.
• Pausar: POST /cards/{card_id}/freeze suspende todas as transações e mantém o saldo. unfreeze reativa o cartão.
• Encerrar: DELETE /cards/{card_id} encerra o cartão definitivamente e devolve o saldo restante para a sua carteira. Não dá para desfazer.

As taxas de sempre valem para a atividade via API, exatamente como no painel: $1 por cartão emitido, $0,30 por transação aprovada (recusas grátis) e recargas de cartão a partir do saldo sem custo. Depósitos abaixo de $300 pagam 2% de taxa; a partir de $300, nada. Veja a seção de preços.

Webhooks

Em vez de ficar consultando, registre um endpoint HTTPS com POST /webhooks, listando os eventos que quer receber (ou ["*"] para todos). Os eventos disponíveis incluem:

• card.created, card.frozen, card.unfrozen, card.terminated, card.funded
• transaction.authorized, transaction.settled, transaction.declined, transaction.refunded
• 3ds.challenge
• deposit.pending, deposit.confirmed

Cada entrega é assinada com HMAC-SHA256 usando o segredo do seu endpoint, que é gerado para você se não informar um. Recalcule a assinatura sobre o corpo bruto da requisição e compare em tempo constante antes de confiar no payload:

import crypto from 'node:crypto';

export function verify(rawBody, signature, secret) {
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Só faça o parse do JSON depois que a verificação passar, e torne o seu handler idempotente para o caso de um evento chegar mais de uma vez.

Erros e limites de requisição

Qualquer resposta diferente de 2xx vem com um corpo JSON contendo um código error estável, que você pode usar na lógica, e uma message legível. Os códigos de status que você vai encontrar são 400 (parâmetros inválidos), 401 (chave ausente ou inválida), 403 (conta não pronta ou API não ativada), 404 (não encontrado) e 429 (limite de requisições excedido).

Os limites são contados por chave de API:

Se receber um 429, espere e tente de novo com backoff exponencial.

Dicas de arquitetura para uma integração confiável

• Armazene o id do cartão, não o número. Busque os dados sob demanda.
• Use metadata e label para ligar os cartões aos seus próprios registros, como um ID de cliente ou de campanha.
• Prefira webhooks a consultas periódicas para transações e desafios 3D Secure.
• Mantenha uma folga de saldo nos cartões que pagam cobranças recorrentes, ou use auto_freeze_at e fund para gerenciar saldos automaticamente.
• Planeje os limites. Os limites do plano da conta continuam valendo: o plano Virtual permite $5.000 por transação e $20.000 por mês, enquanto o Platinum, desbloqueado por um único depósito de $300 ou mais, não tem limites de gastos.

Se você gerencia cartões para uma equipe em vez de escrever código, veja cartões virtuais para equipes. Para contas de anúncios, leia cartões virtuais para anúncios. Pronto para começar? Crie uma conta.

Perguntas frequentes

O que é uma API de cartão virtual?

É uma interface que permite a um software criar e gerenciar cartões de pagamento automaticamente. No USDT Crypto Card, é uma API REST com JSON via HTTPS, autenticada com uma chave secreta sk_live_.

Existe sandbox ou SDK?

Não. Não há ambiente sandbox nem pacotes de SDK oficiais. Você chama a API REST diretamente com qualquer cliente HTTP, e toda chamada é real, então teste com valores pequenos.

Por que minha nova chave de API retorna 403?

A conta ainda não está pronta. onboarding_incomplete significa que você ainda precisa confirmar o e-mail e fazer um primeiro depósito. api_not_enabled significa que o suporte ainda precisa ativar o acesso à API.

Como os webhooks são protegidos?

Cada entrega é assinada com HMAC-SHA256 usando o segredo do seu endpoint. Recalcule a assinatura sobre o corpo bruto e compare em tempo constante antes de confiar no payload.

Cartões via API custam o mesmo que os do painel?

Sim. Valem as mesmas taxas: $1 por cartão, $0,30 por transação aprovada, recargas a partir do saldo sem custo e taxa de depósito de 2% abaixo de $300.