Documentación de API — CryptoTopCard API de Tarjetas Virtuales

Autenticación

Claves API & Autenticación

Todas las solicitudes API requieren un token Bearer. Genera tu clave API desde Panel → Configuración → Claves API.

Seguridad de Clave API

Nunca expongas tu clave en código del lado del cliente. Usa variables de entorno. Las claves con prefijo sk_live_ son de producción, sk_test_ son 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

Límites de Tasa

1,000

Solicitudes / Minuto

50

Creaciones de Tarjeta / Minuto

10,000

Solicitudes / Hora

Códigos de Error

error-response.json

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

200

Solicitud exitosa

201

Recurso creado

400

Parámetros de solicitud inválidos

401

Clave API faltante o inválida

404

Recurso no encontrado

429

Límite de tasa excedido

Tarjetas

Gestión de Tarjetas

Crea, gestiona y controla tarjetas virtuales Visa & Mastercard. Cada tarjeta está aislada con su propio saldo, límites y ciclo de vida.

POST /cards Emitir una nueva tarjeta virtual

Cuerpo de la Solicitud

Parámetro	Tipo		Descripción
bin_id	string	required	Identificador BIN (ej. `491653`). Usa `GET /bins` para listar BINs disponibles.
amount	number	required	Monto de financiación inicial en USD. Mín: $1.00, Máx: $5,000.00
label	string	optional	Etiqueta personalizada para la tarjeta (máx 64 caracteres)
spending_limit	number	optional	Límite de gasto mensual en USD. Por defecto el máximo del BIN.
allowed_categories	string[]	optional	Categorías MCC a incluir en lista blanca (ej. `["advertising", "software"]`)
auto_freeze_at	number	optional	Congelar automáticamente cuando el saldo caiga por debajo de este monto
metadata	object	optional	Pares clave-valor para tu seguimiento interno (máx 20 claves)

Solicitud de Ejemplo

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"}
  }'

Respuesta 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 todas las tarjetas con filtros y paginación

Parámetros de Consulta

Parámetro	Tipo		Descripción
status	string	optional	`active`, `frozen`, `terminated`
bin_id	string	optional	Filtrar por BIN
label	string	optional	Buscar por etiqueta (coincidencia parcial)
sort	string	optional	`created_at`, `balance`, `last_used`. Por defecto: `created_at`
order	string	optional	`asc` o `desc`. Por defecto: `desc`
page	integer	optional	Número de página. Por defecto: `1`
per_page	integer	optional	Elementos por página (1-100). Por defecto: `25`

Respuesta 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} Obtener resumen de tarjeta (sin datos sensibles)

Devuelve información de la tarjeta sin datos sensibles. Usa /cards/{card_id}/details para el PAN completo y CVV.

Respuesta 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 Obtener PAN completo, CVV y vencimiento

Endpoint Sensible

Devuelve PAN completo, CVV y vencimiento. Datos PCI sensibles — nunca registrar ni almacenar sin cifrar. Limitado a 30 sol/min.

Respuesta 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} Actualizar configuración de tarjeta

Cuerpo de la Solicitud

Parámetro	Tipo		Descripción
label	string	optional	Actualizar etiqueta de tarjeta
spending_limit	number	optional	Actualizar límite de gasto mensual
allowed_categories	string[]	optional	Actualizar categorías MCC permitidas
auto_freeze_at	number	optional	Establecer umbral de congelación automática. `0` para desactivar.
metadata	object	optional	Fusionar con metadatos existentes

Respuesta 200 OK

Devuelve el objeto de tarjeta actualizado.

POST /cards/{card_id}/freeze Suspender temporalmente una tarjeta

Suspende todas las transacciones. El saldo se conserva. La tarjeta puede descongelarse después.

Respuesta 200 OK

response.json

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

POST /cards/{card_id}/unfreeze Reactivar una tarjeta congelada

Reactiva transacciones en una tarjeta congelada. Devuelve el objeto de tarjeta con status: "active".

DELETE /cards/{card_id} Terminar permanentemente una tarjeta

Acción Irreversible

La terminación de una tarjeta es permanente. El saldo restante se devuelve a tu billetera al instante.

Respuesta 200 OK

response.json

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

Fondeo

Fondeo de Tarjetas

Agrega o retira fondos de tarjetas individuales. Los fondos provienen del saldo de tu billetera.

POST /cards/{card_id}/fund Agregar fondos a una tarjeta

Cuerpo de la Solicitud

Parámetro	Tipo		Descripción
amount	number	required	Monto en USD a agregar. Mín: $1.00, Máx: $5,000.00

Respuesta 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 fondos de vuelta a la billetera

Cuerpo de la Solicitud

Parámetro	Tipo		Descripción
amount	number	required	Monto en USD a retirar de la tarjeta a la billetera

Respuesta 200 OK

Devuelve saldos actualizados de tarjeta y billetera.

Transacciones

Historial de Transacciones

Ve todas las transacciones de tus tarjetas. Incluye autorizaciones, liquidaciones, reembolsos y rechazos.

GET /transactions Listar todas las transacciones con filtros

Parámetros de Consulta

Parámetro	Tipo		Descripción
card_id	string	optional	Filtrar por tarjeta
type	string	optional	`authorization`, `settlement`, `refund`, `decline`
from	string	optional	Fecha de inicio (ISO 8601)
to	string	optional	Fecha de fin (ISO 8601)
merchant	string	optional	Buscar por nombre de comercio (coincidencia parcial)
min_amount	number	optional	Monto mínimo de transacción
max_amount	number	optional	Monto máximo de transacción
page	integer	optional	Número de página. Por defecto: `1`
per_page	integer	optional	Elementos por página (1-100). Por defecto: `50`

Respuesta 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} Obtener detalles completos de transacción

Devuelve el objeto de transacción completo incluyendo detalles del comercio, código MCC, estado 3DS y cronología de autorización.

Billetera

Billetera & Depósitos

Gestiona tu billetera de cuenta. Deposita crypto, consulta saldos y rastrea depósitos entrantes.

GET /wallet/balance Obtener saldo y estadísticas de billetera

Respuesta 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 Obtener direcciones de depósito crypto

Parámetros de Consulta

Parámetro	Tipo		Descripción
currency	string	optional	`btc`, `eth`, `sol`, `usdt`. Omitir para obtener todos.

Respuesta 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 historial de depósitos

Parámetros de Consulta

Parámetro	Tipo		Descripción
status	string	optional	`pending`, `confirmed`, `expired`
currency	string	optional	Filtrar por criptomoneda

Respuesta 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

Selección de BIN

Lista los rangos BIN disponibles con sus capacidades, límites y tasas de aceptación.

GET /bins Listar todos los BINs disponibles

Respuesta 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

Autenticación 3D Secure

Recupera desafíos 3DS y códigos OTP. Todas las tarjetas están inscritas en 3DS 2.0 automáticamente.

GET /3ds Listar desafíos 3DS pendientes

Parámetros de Consulta

Parámetro	Tipo		Descripción
card_id	string	optional	Filtrar por tarjeta
status	string	optional	`pending`, `completed`, `expired`

Respuesta 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} Obtener un OTP 3DS específico

Devuelve el objeto de desafío 3DS completo incluyendo el código OTP. Los OTP expiran después de 5 minutos.

Webhooks

Webhooks & Eventos

Recibe notificaciones en tiempo real cuando ocurren eventos. Las cargas están firmadas con HMAC-SHA256.

Eventos Disponibles

card.createdSe emitió una nueva tarjeta

card.frozenSe congeló una tarjeta

card.unfrozenSe descongeló una tarjeta

card.terminatedSe terminó una tarjeta

card.fundedSe agregaron fondos a una tarjeta

transaction.authorizedTransacción autorizada

transaction.settledTransacción liquidada

transaction.declinedTransacción rechazada

transaction.refundedReembolso procesado

3ds.challengeVerificación 3DS requerida

deposit.pendingDepósito crypto detectado

deposit.confirmedDepósito crypto confirmado

Verificación de Firma

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 un endpoint de webhook

Cuerpo de la Solicitud

Parámetro	Tipo		Descripción
url	string	required	URL del endpoint HTTPS para recibir eventos
events	string[]	required	Tipos de evento a suscribir. Usa `["*"]` para todos.
secret	string	optional	Secreto de firma personalizado. Se genera automáticamente si se omite.

Respuesta 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

Devuelve array de todos los endpoints de webhook registrados con sus suscripciones de eventos y estado.

DELETE /webhooks/{webhook_id} Eliminar un webhook

Elimina permanentemente el webhook. No se entregarán más eventos a este endpoint.

SDKs

SDKs & Bibliotecas

Bibliotecas cliente oficiales para tu stack. Todos los SDKs soportan entornos de producción y sandbox.

Python

pip install cryptotopcard

Node.js

npm i cryptotopcard

Go

go get cryptotopcard

Inicio Rápido — Python

quickstart.py

from cryptotopcard import Client

client = Client("sk_live_your_api_key")

# Crear una tarjeta
card = client.cards.create(
    bin_id="491653",
    amount=500,
    label="Ad Spend"
)
print(card.id, card.last4)

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

# Fondear la tarjeta
client.cards.fund(card.id, amount=200)

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

Inicio Rápido — Node.js

quickstart.js

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

const client = new CryptoTopCard('sk_live_your_api_key');

// Crear una tarjeta
const card = await client.cards.create({
  binId: '491653',
  amount: 500,
  label: 'Ad Spend',
});

// Obtener 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 Referencia

Claves API & Autenticación

Seguridad de Clave API

Gestión de Tarjetas

Endpoint Sensible

Acción Irreversible

Fondeo de Tarjetas

Historial de Transacciones

Billetera & Depósitos

Selección de BIN

Autenticación 3D Secure

Webhooks & Eventos

SDKs & Bibliotecas

Python

Node.js

Go

Bienvenido de nuevo

Crear Cuenta

Cuenta Creada