Documentação da API — CryptoTopCard API de Cartões Virtuais

Autenticação

Chaves API & Autenticação

Todas as requisições API requerem um token Bearer. Gere sua chave API em Painel → Configurações → Chaves API.

Segurança da Chave API

Nunca exponha sua chave em código do lado do cliente. Use variáveis de ambiente. Chaves com prefixo sk_live_ são de produção, sk_test_ são de sandbox.

request-headers

Authorization: Bearer sk_live_your_api_key_here
Content-Type: application/json
X-Idempotency-Key: optional-unique-key-for-safe-retries

Limites de Taxa

1,000

Requisições / Minuto

50

Criações de Cartão / Minuto

10,000

Requisições / Hora

Códigos de Erro

error-response.json

{
  "error": "insufficient_funds",
  "message": "Your wallet balance is too low to fund this card.",
  "code": 400,
  "request_id": "req_7f8a9b2c3d4e"
}

200

Requisição bem-sucedida

201

Recurso criado

400

Parâmetros de requisição inválidos

401

Chave API ausente ou inválida

404

Recurso não encontrado

429

Limite de taxa excedido

Cartões

Gerenciamento de Cartões

Crie, gerencie e controle cartões virtuais Visa & Mastercard. Cada cartão é isolado com seu próprio saldo, limites e ciclo de vida.

POST /cards Emitir um novo cartão virtual

Corpo da Requisição

Parâmetro	Tipo		Descrição
bin_id	string	required	Identificador BIN (ex. `491653`). Use `GET /bins` para listar BINs disponíveis.
amount	number	required	Valor de financiamento inicial em USD. Mín: $1.00, Máx: $5,000.00
label	string	optional	Rótulo personalizado para o cartão (máx 64 caracteres)
spending_limit	number	optional	Limite de gastos mensal em USD. Padrão: máximo do BIN.
allowed_categories	string[]	optional	Categorias MCC para lista branca (ex. `["advertising", "software"]`)
auto_freeze_at	number	optional	Congelar automaticamente quando o saldo cair abaixo deste valor
metadata	object	optional	Pares chave-valor para rastreamento interno (máx 20 chaves)

Exemplo de Requisição

curl

curl -X POST https://api.cryptotopcard.com/v1/cards \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "bin_id": "491653",
    "amount": 500,
    "label": "Meta Ads Campaign #12",
    "spending_limit": 2000,
    "allowed_categories": ["advertising"],
    "metadata": {"campaign": "spring_2026"}
  }'

Resposta 201 Created

response.json

{
  "id": "card_8xK2m9Lp4q",
  "bin_id": "491653",
  "network": "visa",
  "last4": "2039",
  "status": "active",
  "balance": 500.00,
  "spending_limit": 2000.00,
  "label": "Meta Ads Campaign #12",
  "allowed_categories": ["advertising"],
  "auto_freeze_at": null,
  "metadata": { "campaign": "spring_2026" },
  "created_at": "2026-04-15T12:00:00Z",
  "expires_at": "2029-04-15T23:59:59Z"
}

GET /cards Listar todos os cartões com filtros e paginação

Parâmetros de Consulta

Parâmetro	Tipo		Descrição
status	string	optional	`active`, `frozen`, `terminated`
bin_id	string	optional	Filtrar por BIN
label	string	optional	Buscar por rótulo (correspondência parcial)
sort	string	optional	`created_at`, `balance`, `last_used`. Padrão: `created_at`
order	string	optional	`asc` ou `desc`. Padrão: `desc`
page	integer	optional	Número da página. Padrão: `1`
per_page	integer	optional	Itens por página (1-100). Padrão: `25`

Resposta 200 OK

response.json

{
  "data": [
    {
      "id": "card_8xK2m9Lp4q",
      "bin_id": "491653",
      "network": "visa",
      "last4": "2039",
      "status": "active",
      "balance": 487.50,
      "label": "Meta Ads Campaign #12",
      "created_at": "2026-04-15T12:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 142,
    "total_pages": 6
  }
}

GET /cards/{card_id} Obter resumo do cartão (sem dados sensíveis)

Retorna informações do cartão sem dados sensíveis. Use /cards/{card_id}/details para o PAN completo e CVV.

Resposta 200 OK

response.json

{
  "id": "card_8xK2m9Lp4q",
  "bin_id": "491653",
  "network": "visa",
  "last4": "2039",
  "status": "active",
  "balance": 487.50,
  "spending_limit": 2000.00,
  "total_spent": 12.50,
  "transaction_count": 3,
  "label": "Meta Ads Campaign #12",
  "metadata": { "campaign": "spring_2026" },
  "created_at": "2026-04-15T12:00:00Z",
  "expires_at": "2029-04-15T23:59:59Z",
  "last_used_at": "2026-04-15T14:32:00Z"
}

GET /cards/{card_id}/details Obter PAN completo, CVV e validade

Endpoint Sensível

Retorna PAN completo, CVV e validade. Dados PCI sensíveis — nunca registrar ou armazenar sem criptografia. Limitado a 30 req/min.

Resposta 200 OK

response.json

{
  "id": "card_8xK2m9Lp4q",
  "pan": "4916531288472039",
  "cvv": "847",
  "exp_month": 4,
  "exp_year": 2029,
  "holder_name": "ANONYMOUS",
  "billing_address": {
    "line1": "123 Privacy Street",
    "city": "Wilmington",
    "state": "DE",
    "zip": "19801",
    "country": "US"
  }
}

PATCH /cards/{card_id} Atualizar configurações do cartão

Corpo da Requisição

Parâmetro	Tipo		Descrição
label	string	optional	Atualizar rótulo do cartão
spending_limit	number	optional	Atualizar limite de gastos mensal
allowed_categories	string[]	optional	Atualizar categorias MCC permitidas
auto_freeze_at	number	optional	Definir limite de congelamento automático. `0` para desativar.
metadata	object	optional	Mesclar com metadados existentes

Resposta 200 OK

Retorna o objeto do cartão atualizado.

POST /cards/{card_id}/freeze Suspender temporariamente um cartão

Suspende todas as transações. O saldo é preservado. O cartão pode ser descongelado depois.

Resposta 200 OK

response.json

{ "id": "card_8xK2m9Lp4q", "status": "frozen", "frozen_at": "2026-04-15T15:00:00Z" }

POST /cards/{card_id}/unfreeze Reativar um cartão congelado

Reativa transações em um cartão congelado. Retorna o objeto do cartão com status: "active".

DELETE /cards/{card_id} Encerrar permanentemente um cartão

Ação Irreversível

O encerramento de um cartão é permanente. O saldo restante é devolvido à sua carteira instantaneamente.

Resposta 200 OK

response.json

{
  "id": "card_8xK2m9Lp4q",
  "status": "terminated",
  "refunded_amount": 487.50,
  "terminated_at": "2026-04-15T16:00:00Z"
}

Financiamento

Financiamento de Cartões

Adicione ou retire fundos de cartões individuais. Os fundos vêm do saldo da sua carteira.

POST /cards/{card_id}/fund Adicionar fundos a um cartão

Corpo da Requisição

Parâmetro	Tipo		Descrição
amount	number	required	Valor em USD para adicionar. Mín: $1.00, Máx: $5,000.00

Resposta 200 OK

response.json

{
  "id": "card_8xK2m9Lp4q",
  "previous_balance": 487.50,
  "funded_amount": 200.00,
  "new_balance": 687.50,
  "wallet_balance": 1312.50
}

POST /cards/{card_id}/withdraw Retirar fundos de volta para a carteira

Corpo da Requisição

Parâmetro	Tipo		Descrição
amount	number	required	Valor em USD para retirar do cartão de volta para a carteira

Resposta 200 OK

Retorna saldos atualizados do cartão e da carteira.

Transações

Histórico de Transações

Veja todas as transações dos seus cartões. Inclui autorizações, liquidações, reembolsos e recusas.

GET /transactions Listar todas as transações com filtros

Parâmetros de Consulta

Parâmetro	Tipo		Descrição
card_id	string	optional	Filtrar por cartão
type	string	optional	`authorization`, `settlement`, `refund`, `decline`
from	string	optional	Data de início (ISO 8601)
to	string	optional	Data de fim (ISO 8601)
merchant	string	optional	Buscar por nome do comerciante (correspondência parcial)
min_amount	number	optional	Valor mínimo da transação
max_amount	number	optional	Valor máximo da transação
page	integer	optional	Número da página. Padrão: `1`
per_page	integer	optional	Itens por página (1-100). Padrão: `50`

Resposta 200 OK

response.json

{
  "data": [
    {
      "id": "txn_a1b2c3d4",
      "card_id": "card_8xK2m9Lp4q",
      "type": "settlement",
      "amount": -12.50,
      "currency": "USD",
      "merchant": {
        "name": "FACEBK ADS",
        "category": "advertising",
        "mcc": "7311",
        "country": "US"
      },
      "balance_after": 487.50,
      "created_at": "2026-04-15T14:32:00Z"
    }
  ],
  "pagination": { "page": 1, "per_page": 50, "total": 328 }
}

GET /transactions/{txn_id} Obter detalhes completos da transação

Retorna o objeto de transação completo incluindo detalhes do comerciante, código MCC, status 3DS e cronologia de autorização.

Carteira

Carteira & Depósitos

Gerencie sua carteira de conta. Deposite crypto, verifique saldos e acompanhe depósitos recebidos.

GET /wallet/balance Obter saldo e estatísticas da carteira

Resposta 200 OK

response.json

{
  "balance": 1312.50,
  "currency": "USD",
  "pending_deposits": 500.00,
  "total_deposited": 15000.00,
  "total_spent": 13687.50,
  "cards_active": 8,
  "cards_total_balance": 2450.00
}

GET /wallet/deposit-address Obter endereços de depósito crypto

Parâmetros de Consulta

Parâmetro	Tipo		Descrição
currency	string	optional	`btc`, `eth`, `sol`, `usdt`. Omitir para obter todos.

Resposta 200 OK

response.json

{
  "addresses": {
    "btc": "bc1qxy2kgdygjrsqtzq2n0yrf...",
    "eth": "0x742d35Cc6634C0532925a3b...",
    "sol": "7xKXtg2CW87d97TXJSDpbD5j...",
    "usdt": "0x742d35Cc6634C0532925a3b..."
  },
  "networks": {
    "btc": "bitcoin",
    "eth": "ethereum",
    "sol": "solana",
    "usdt": "erc-20"
  },
  "min_deposit": {
    "btc": "0.0001",
    "eth": "0.005",
    "sol": "0.1",
    "usdt": "5.00"
  }
}

GET /wallet/deposits Listar histórico de depósitos

Parâmetros de Consulta

Parâmetro	Tipo		Descrição
status	string	optional	`pending`, `confirmed`, `expired`
currency	string	optional	Filtrar por criptomoeda

Resposta 200 OK

response.json

{
  "data": [
    {
      "id": "dep_x9y8z7w6",
      "currency": "btc",
      "amount_crypto": "0.0075",
      "amount_usd": 500.00,
      "fee_usd": 10.00,
      "credited_usd": 490.00,
      "status": "confirmed",
      "tx_hash": "3a1b2c3d4e5f...",
      "confirmations": 6,
      "created_at": "2026-04-15T10:00:00Z",
      "confirmed_at": "2026-04-15T10:42:00Z"
    }
  ]
}

BINs

Seleção de BIN

Liste as faixas BIN disponíveis com suas capacidades, limites e taxas de aceitação.

GET /bins Listar todos os BINs disponíveis

Resposta 200 OK

response.json

{
  "data": [
    {
      "id": "491653",
      "network": "visa",
      "type": "advertising",
      "issuer_country": "US",
      "3ds": true,
      "apple_pay": true,
      "google_pay": true,
      "max_transaction": 5000.00,
      "max_monthly": 50000.00,
      "acceptance_rate": 97.2,
      "best_for": ["meta_ads", "google_ads", "tiktok_ads"]
    },
    {
      "id": "531993",
      "network": "mastercard",
      "type": "everyday",
      "issuer_country": "US",
      "3ds": true,
      "apple_pay": true,
      "google_pay": true,
      "max_transaction": 1000.00,
      "max_monthly": 10000.00,
      "acceptance_rate": 95.8,
      "best_for": ["subscriptions", "saas", "shopping"]
    }
  ]
}

3D Secure

Autenticação 3D Secure

Recupere desafios 3DS e códigos OTP. Todos os cartões são inscritos no 3DS 2.0 automaticamente.

GET /3ds Listar desafios 3DS pendentes

Parâmetros de Consulta

Parâmetro	Tipo		Descrição
card_id	string	optional	Filtrar por cartão
status	string	optional	`pending`, `completed`, `expired`

Resposta 200 OK

response.json

{
  "data": [
    {
      "id": "3ds_m4n5o6p7",
      "card_id": "card_8xK2m9Lp4q",
      "merchant": "SPOTIFY",
      "amount": 9.99,
      "otp": "847291",
      "status": "pending",
      "expires_at": "2026-04-15T15:05:00Z",
      "created_at": "2026-04-15T15:00:00Z"
    }
  ]
}

GET /3ds/{challenge_id} Obter um OTP 3DS específico

Retorna o objeto de desafio 3DS completo incluindo o código OTP. Os OTPs expiram após 5 minutos.

Webhooks

Webhooks & Eventos

Receba notificações em tempo real quando eventos ocorrerem. As cargas são assinadas com HMAC-SHA256.

Eventos Disponíveis

card.createdUm novo cartão foi emitido

card.frozenUm cartão foi congelado

card.unfrozenUm cartão foi descongelado

card.terminatedUm cartão foi encerrado

card.fundedFundos adicionados a um cartão

transaction.authorizedTransação autorizada

transaction.settledTransação liquidada

transaction.declinedTransação recusada

transaction.refundedReembolso processado

3ds.challengeVerificação 3DS necessária

deposit.pendingDepósito crypto detectado

deposit.confirmedDepósito crypto confirmado

Verificação de Assinatura

verify-webhook.py

import hmac, hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

POST /webhooks Registrar um endpoint de webhook

Corpo da Requisição

Parâmetro	Tipo		Descrição
url	string	required	URL do endpoint HTTPS para receber eventos
events	string[]	required	Tipos de evento para assinar. Use `["*"]` para todos.
secret	string	optional	Segredo de assinatura personalizado. Gerado automaticamente se omitido.

Resposta 201 Created

response.json

{
  "id": "wh_r5s6t7u8",
  "url": "https://yourapp.com/webhooks/ctc",
  "events": ["transaction.authorized", "transaction.declined"],
  "secret": "whsec_a1b2c3d4e5f6...",
  "active": true,
  "created_at": "2026-04-15T12:00:00Z"
}

GET /webhooks Listar webhooks registrados

Retorna array de todos os endpoints de webhook registrados com suas assinaturas de eventos e status.

DELETE /webhooks/{webhook_id} Excluir um webhook

Remove permanentemente o webhook. Nenhum evento será mais entregue a este endpoint.

SDKs

SDKs & Bibliotecas

Bibliotecas cliente oficiais para seu stack. Todos os SDKs suportam ambientes de produção e sandbox.

Python

pip install cryptotopcard

Node.js

npm i cryptotopcard

Go

go get cryptotopcard

Início Rápido — Python

quickstart.py

from cryptotopcard import Client

client = Client("sk_live_your_api_key")

# Criar um cartão
card = client.cards.create(
    bin_id="491653",
    amount=500,
    label="Ad Spend"
)
print(card.id, card.last4)

# Obter detalhes completos (PAN, CVV)
details = client.cards.details(card.id)
print(details.pan, details.cvv)

# Financiar o cartão
client.cards.fund(card.id, amount=200)

# Listar transações
txns = client.transactions.list(card_id=card.id)
for t in txns.data:
    print(t.merchant.name, t.amount)

Início Rápido — Node.js

quickstart.js

const { CryptoTopCard } = require('cryptotopcard');

const client = new CryptoTopCard('sk_live_your_api_key');

// Criar um cartão
const card = await client.cards.create({
  binId: '491653',
  amount: 500,
  label: 'Ad Spend',
});

// Obter OTPs 3DS
const challenges = await client.threeds.list({
  cardId: card.id,
  status: 'pending',
});

// Configurar webhooks
await client.webhooks.create({
  url: 'https://yourapp.com/hooks',
  events: ['transaction.authorized', '3ds.challenge'],
});

API Referência

Chaves API & Autenticação

Segurança da Chave API

Gerenciamento de Cartões

Endpoint Sensível

Ação Irreversível

Financiamento de Cartões

Histórico de Transações

Carteira & Depósitos

Seleção de BIN

Autenticação 3D Secure

Webhooks & Eventos

SDKs & Bibliotecas

Python

Node.js

Go

Bem-vindo de volta

Criar Conta

Conta Criada