Tovanix
Tovanix

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…