API de cartões virtuais
Emita e gerencie cartões virtuais Visa / Mastercard em lote por API, abastecidos com USDT — para pagamentos de assinaturas, publicidade e compras internacionais.
- Consulta de BINs: BINs disponíveis, regiões aceitas e faixas de limites
- Emissão e recarga: crie cartões com o BIN escolhido e recarregue conforme necessário
- Gerenciamento de cartões: congele, descongele, encerre e consulte os dados do cartão com segurança
- Transações e webhooks: histórico por transação e eventos de autorização e liquidação em tempo real
Visão geral
A API aberta de cartões virtuais permite abrir cartões, listar BINs, ler detalhes, obter OTP 3DS, consultar transações, recarregar e cancelar — além de ler o saldo USD e obter um endereço fixo de depósito TRON. Todos os endpoints retornam JSON unificado (code/message/data, code=0 indica sucesso).
URL base = endereço do gateway (origem deste site). Cartões usam prefixo /api/v1/vcard; conta, /api/v1/account.
Todos os valores em USD; abertura/recarga debitam o saldo USD da plataforma (somente pagamento por saldo). Saldo insuficiente retorna erro.
Autenticação e assinatura
Endpoints de leitura (BINs, lista, transações, pedidos, saldo, depósito) aceitam as duas chaves simples. Movimentação de recursos ou dados sensíveis exige também assinatura HMAC + timestamp + nonce: abrir, recarregar, cancelar, devolver saldo, congelar/descongelar, detalhes completos (details) e código 3DS (code). Só a chave simples vazada não permite mover recursos ou ler dados sensíveis.
Entre no console → Ferramentas e configurações → Gerenciamento de API → Criar chave; copie API Key e Secret Key (segredo exibido uma vez).
Abrir, recarregar, cancelar, devolver saldo, congelar/descongelar, detalhes (número completo e CVV) e código 3DS só aceitam requisições assinadas; apenas chaves simples retornam 401. Outras leituras não exigem assinatura.
Saldo da conta
GET /api/v1/account/balance
Leia o saldo USD atual e, quando possível, o endereço fixo TRON (deposit_address é null se o pool estiver temporariamente indisponível; o saldo ainda retorna).
Endereço fixo TRON
GET /api/v1/account/deposit-address
Obtenha/atribua seu endereço fixo exclusivo de depósito TRON (USDT/TRX·TRC20). Sem pedido — qualquer valor enviado é convertido automaticamente para USD e creditado, ideal para recarga automatizada por API. Após atribuir, o endereço fica fixo.
Campos da resposta
Envie USDT ou TRX; após confirmação pelo scanner de blocos, é convertido automaticamente para USD pela cotação atual e creditado no saldo — sem callback necessário.
Status dos serviços
GET /api/v1/vcard/info
Retorna se o serviço de cartões virtuais está ativado e o saldo USD atual.
Campos da resposta
Se o saldo da conta não puder ser consultado, o endpoint retorna HTTP 503 em vez de balance: 0. Ao receber 503, tente novamente mais tarde e não interprete como saldo zero.
BINs de cartões
GET /api/v1/vcard/bins
Retorna os BINs. Taxas são preços finais com acréscimo, calculados pelo nível de API conforme consumo dos últimos 30 dias (maior gasto = menor taxa). can_open=false indica BIN apenas para recarga (cartões existentes, sem novas aberturas).
Abrir cartão Assinado
POST /api/v1/vcard/cards
Crie um cartão. O sistema debita o saldo USD (taxa de abertura + taxa de recarga + valor do cartão); o pedido é processado assincronamente por fila.
Campos da resposta
A abertura é assíncrona: após receber order_id e status=queued, consulte Detalhes do pedido até completed. Falhas são reembolsadas automaticamente ao saldo.
Quando a requisição expira ou a conexão cai, a cobrança pode já ter ocorrido. Não tente novamente com um novo número de pedido: reenvie o mesmo out_trade_no (um pedido existente é retornado sem nova cobrança) ou consulte o resultado por GET /api/v1/vcard/orders/by-trade-no/:out_trade_no. Requisições sem out_trade_no não têm essa proteção, e uma nova tentativa pode cobrar novamente.
Lista de cartões
GET /api/v1/vcard/cards
Retorna todos os cartões da conta (últimos 4 dígitos, saldo, uso e cancelamento).
Campos da resposta
A lista de cartões retorna apenas os campos da tabela acima. can_return e fee_return são retornados apenas para alguns BINs; quando ausentes, considere que o cartão não oferece devolução de saldo.
Detalhes do cartão Assinado
GET /api/v1/vcard/cards/:id/details
Retorna dados sensíveis de um cartão: número completo, CVV, validade e titular. Só permite consultar seus cartões.
Campos da resposta
Observação: a tabela lista campos garantidos pela plataforma; a resposta pode trazer outros campos, conforme o retorno real.
Este endpoint retorna número completo e CVV — chame apenas de um servidor confiável, nunca exponha em frontends ou registros.
Transações
GET /api/v1/vcard/cards/:id/transactions
Retorna transações/extratos (gastos, recargas etc.); cada consulta sincroniza em tempo real os lançamentos mais recentes.
Campos da resposta
Observação: a tabela lista campos garantidos pela plataforma; a resposta pode trazer outros campos, conforme o retorno real.
Código OTP Assinado
GET /api/v1/vcard/cards/:id/code
Obtenha o OTP 3DS mais recente para verificar pagamentos.
Recarregar Assinado
POST /api/v1/vcard/cards/:id/recharge
Recarregue um cartão existente. Debita o saldo USD (valor + taxa); processado assincronamente por fila.
Campos da resposta
Quando a requisição expira ou a conexão cai, a cobrança pode já ter ocorrido. Não tente novamente com um novo número de pedido: reenvie o mesmo out_trade_no (um pedido existente é retornado sem nova cobrança) ou consulte o resultado por GET /api/v1/vcard/orders/by-trade-no/:out_trade_no. Requisições sem out_trade_no não têm essa proteção, e uma nova tentativa pode cobrar novamente.
Cancelar Assinado
POST /api/v1/vcard/cards/:id/cancel
Solicite cancelamento. É assíncrono: após o banco confirmar (pode levar dias), o saldo restante é reembolsado automaticamente à conta.
Devolução de saldo Assinado
POST /api/v1/vcard/cards/:id/return
Devolva o saldo à conta sem cancelar o cartão. A taxa sai do valor devolvido e o líquido é creditado automaticamente. Só alguns BINs suportam: chame quando can_return for true; fee_return é a taxa do BIN.
Só uma devolução por cartão de cada vez. Nova solicitação enquanto a anterior está em andamento retorna 400 — aguarde o estado final em vez de repetir.
Bloquear / desbloquear Assinado
POST /api/v1/vcard/cards/:id/freeze
Congele ou descongele um cartão. Cada operação tem pequena taxa (status_fee da lista). Só se can_freeze for true; retorna 400 se já está no estado desejado ou há operação em andamento.
Recarga automática (regras de saldo) Assinado
GET /api/v1/vcard/balance-rules
GET /api/v1/vcard/cards/:id/balance-rule
PUT /api/v1/vcard/cards/:id/balance-rule
DELETE /api/v1/vcard/cards/:id/balance-rule
POST /api/v1/vcard/cards/:id/balance-rule/resume
Recarrega um cartão automaticamente quando o saldo fica abaixo de um valor definido, ou apenas envia um aviso. Cada cartão tem uma regra; PUT cria ou substitui. As recargas automáticas usam o mesmo caminho de cobrança das manuais (mesmos limites e taxas) e rodam quando o saldo muda ou numa verificação a cada minuto.
Limites de segurança: são obrigatórios um número diário de recargas (1–10, no fuso da sua conta) e um teto mensal de valor. A regra pausa sozinha e avisa você se o cartão for congelado ou estiver em cancelamento, se o emissor recusar por fraude, se 3 transações seguidas forem recusadas ou se o saldo da conta faltar 3 vezes seguidas. Chame resume para retomar (regras pausadas pela plataforma não podem ser retomadas por você).
Chaves de API com limite diário de gastos não podem criar nem retomar a recarga automática (403, código 4035): a plataforma cobra as recargas automáticas em segundo plano, fora do limite da chave. Regras só de aviso não são afetadas.
Assinaturas
GET /api/v1/vcard/subscriptions
Cobranças recorrentes identificadas nas transações dos seus cartões ativos (somente leitura, calculado na hora): cobranças repetidas do mesmo estabelecimento com cerca de uma semana, um mês ou um ano de intervalo contam como assinatura. Para parar uma, congele ou cancele o cartão.
Estabelecimentos permitidos Assinado
GET /api/v1/vcard/merchant-locks
GET /api/v1/vcard/cards/:id/merchant-lock
PUT /api/v1/vcard/cards/:id/merchant-lock
DELETE /api/v1/vcard/cards/:id/merchant-lock
Define com quais estabelecimentos um cartão pode ser usado. Se aparecer uma transação de outro estabelecimento, o cartão é congelado automaticamente (uma taxa de congelamento) ou você só recebe um aviso. Só as transações depois de salvar são verificadas, e o congelamento é posterior: a primeira transação fora da lista já foi autorizada.
Grupos de cartões
GET /api/v1/vcard/groups
POST /api/v1/vcard/groups
PUT /api/v1/vcard/groups/:gid
DELETE /api/v1/vcard/groups/:gid
POST /api/v1/vcard/cards/group
Organize os cartões em grupos, cada um com orçamento mensal opcional: você recebe um aviso ao chegar a 80% e outro ao ultrapassar; as transações nunca são bloqueadas. Um cartão fica em um só grupo; group_id 0 tira o cartão do grupo. Até 20 grupos.
Extrato mensal
GET /api/v1/vcard/bill/export
As transações de cartão de um mês, opcionalmente de um só cartão ou grupo, da mais antiga para a mais recente. Inclui só as transações do período em que você teve o cartão; se passar de 20.000 linhas você recebe 400 — exporte por cartão ou por grupo.
Lista de pedidos
GET /api/v1/vcard/orders
Lista paginada de pedidos de abertura/recarga/cancelamento.
Detalhes do pedido
GET /api/v1/vcard/orders/:id
Consulte o progresso de um pedido para acompanhar abertura/recarga.
Retorna um objeto com os mesmos campos do pedido em "Consultar pedidos".
Consultar pedido pelo seu próprio número
GET /api/v1/vcard/orders/by-trade-no/:out_trade_no
Consulta um pedido pelo out_trade_no informado na abertura ou recarga do cartão. A resposta é a mesma de "Detalhes do pedido". Retorna 404 se o número não existir.
Atualizar observação
PUT /api/v1/vcard/cards/:id/remark
Defina uma observação no cartão (máximo 60 caracteres).
Notificações por webhook
Quando há eventos (abertura / recarga / cancelamento, nova transação, novo 3DS), a plataforma envia HTTP POST (JSON) ao seu endpoint — sem consulta periódica. Configure em Console → Cartão virtual → Integração de API (ativação, URL, Secret de assinatura e eventos; nenhum evento marcado = todos).
Contrato de entrega: URL https pública; payload JSON plano com todos os valores em texto; resposta 2xx indica sucesso, caso contrário há novas tentativas com espera exponencial 30s → 1min → 2min → 5min → 10min, até 10. Mantêm notify_id — deduplique para idempotência.
Campos comuns (em todos os eventos; específicos abaixo):
Verificação: todos os campos não vazios exceto "sign", ordenados por chave crescente, unidos como k=v&k2=v2; calcule HMAC-SHA256 (hexadecimal minúsculo) com Secret e compare com sign. Exija também sign_ts em ±5 minutos e nonce inédito. Recuse com 401 se qualquer verificação falhar.
Eventos e campos específicos:
Perguntas frequentes
Em quanto tempo posso usar um cartão e onde posso pagar?
A emissão retorna os dados do cartão em segundos, e ele funciona imediatamente onde pagamentos online Visa / Mastercard são aceitos — normalmente assinaturas de serviços de IA, recargas de plataformas de publicidade e comércio eletrônico internacional.
Como investigo uma transação recusada?
Consulte o endpoint de histórico de transações para obter o código do motivo da recusa daquela autorização — geralmente saldo insuficiente, uma categoria de estabelecimento restrita ou um bloqueio de controle de risco. Os eventos de autorização e liquidação também são enviados por webhooks para conciliação.
Páginas relacionadas: Cartões virtuais · Documentação da API · Pagamentos com cripto em várias redes
Carregando…