API de tarjetas virtuales: cómo automatizar la emisión de tarjetas con código

Para qué sirve una API de emisión de tarjetas

Emitir unas pocas tarjetas a mano está bien. Emitir una tarjeta por cada nuevo cliente, campaña o proveedor, y mantener cada una con saldo, se vuelve repetitivo muy rápido. Una API de emisión de tarjetas convierte esos pasos en código:

• Crea una tarjeta por entidad automáticamente, por ejemplo cuando un nuevo cliente se registra en tu CRM.
• Recarga tarjetas de forma programada o cuando su saldo baja.
• Congela tarjetas al instante cuando se alcanza un presupuesto o termina un contrato.
• Sincroniza transacciones con tus herramientas de contabilidad o de reportes.
• Reacciona a eventos en tiempo real mediante webhooks en lugar de consultar una y otra vez.

La API hace lo mismo que el panel, pero desde tu servidor. Cada tarjeta que emites y cada carga que haces se pagan con el saldo de tu cuenta, que recargas con depósitos en cripto y que siempre se mantiene en USDT.

Cómo obtener acceso a la API de tarjetas virtuales

El acceso lleva tres pasos:

1. Crea una clave. Abre el acceso a la API en tu panel y genera una clave. Las claves empiezan con sk_live_.
2. Pide que la activen. Confirma tu correo y haz un primer depósito; luego pide al soporte (mediante un ticket en el panel) que habilite la API para tu cuenta.
3. Haz una llamada. Consulta tu saldo y después emite tu primera tarjeta.

Hasta que tu cuenta esté lista, una clave válida recibe una respuesta 403. Verás el código de error onboarding_incomplete hasta que confirmes tu correo y hagas un primer depósito, y después api_not_enabled hasta que se active el acceso a la API.

No hay un entorno sandbox separado ni paquetes SDK oficiales. Llamas a la API REST directamente con cualquier cliente HTTP, lo que simplifica la integración pero significa que todas las llamadas son reales. Haz pruebas con montos pequeños.

Conceptos básicos: URL base, autenticación y formato

• URL base: https://usdtcryptocard.com/api/v1
• Autenticación: envía tu clave como token Bearer en el encabezado Authorization de cada solicitud.
• Formato: JSON sobre HTTPS. Los montos están en dólares estadounidenses con dos decimales. Las marcas de tiempo usan ISO 8601 en UTC.
• Paginación: los endpoints de listas aceptan page y per_page.

Mantén la clave en tu servidor. Cualquiera que la tenga puede mover dinero de tu cuenta, así que cárgala desde una variable de entorno y nunca la incluyas en código de navegador o de apps móviles.

Tu primera llamada

Consultar tu saldo es una primera solicitud segura:

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

La respuesta muestra tu saldo en USDT, los depósitos pendientes y lo que hay en tus tarjetas:

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

Los endpoints

La API tiene 15 endpoints repartidos en seis recursos.

Los parámetros completos y los ejemplos de respuesta están en la referencia de la API.

Emitir una tarjeta desde código

Al crear una tarjeta eliges un BIN y la cargas desde tu saldo en la misma solicitud. Los campos son:

• bin_id (obligatorio): el BIN en el que se emite. Consulta las opciones con GET /bins.
• amount (obligatorio): la carga inicial en USD, que se descuenta de tu saldo. El mínimo es $50, y la comisión de emisión de $1 se cobra aparte.
• label: el nombre que tú le das a la tarjeta.
• spending_limit: un límite de gasto en USD.
• allowed_categories: categorías de comercio en las que se puede usar la tarjeta, como publicidad o software. Todo lo demás se rechaza.
• auto_freeze_at: congela la tarjeta automáticamente cuando su saldo baja de este monto.
• metadata: pares clave-valor para tu propio seguimiento.

Esta es la misma solicitud en 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();

Una llamada correcta devuelve 201 con el objeto de la tarjeta: su id, BIN, red, últimos cuatro dígitos, estado, saldo, y tu etiqueta y metadatos. El resumen omite a propósito el número completo y el CVV.

Cómo obtener el número de la tarjeta de forma segura

GET /cards/{card_id}/details devuelve el número completo de la tarjeta, el CVV y el vencimiento. Trátalo como información sensible: nunca registres la respuesta en logs ni la guardes sin cifrar, y pídela solo cuando de verdad necesites entregar los datos a una persona o a una pantalla de pago. Este endpoint tiene un límite de solicitudes más estricto que el resto.

Recargar, congelar y cerrar

• Recargar: POST /cards/{card_id}/fund con un amount pasa dinero de tu saldo a la tarjeta. Se puede gastar de inmediato.
• Retirar fondos: POST /cards/{card_id}/withdraw devuelve el saldo de la tarjeta a tu billetera.
• Pausar: POST /cards/{card_id}/freeze suspende todas las transacciones y conserva el saldo. unfreeze reactiva la tarjeta.
• Cerrar: DELETE /cards/{card_id} cancela la tarjeta de forma permanente y devuelve el saldo restante a tu billetera. No se puede deshacer.

A la actividad por API se le aplican las comisiones habituales, exactamente igual que en el panel: $1 por tarjeta emitida, $0.30 por transacción aprobada (los rechazos son gratis) y recargas de tarjeta gratuitas desde tu saldo. Los depósitos de menos de $300 tienen una comisión del 2%; los de $300 o más, ninguna. Consulta la sección de precios.

Webhooks

En lugar de consultar periódicamente, registra un endpoint HTTPS con POST /webhooks, indicando los eventos que quieres recibir (o ["*"] para todos). Entre los eventos disponibles están:

• 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 envío se firma con HMAC-SHA256 usando el secreto de tu endpoint, que se genera automáticamente si no proporcionas uno. Vuelve a calcular la firma sobre el cuerpo sin procesar de la solicitud y compárala en tiempo constante antes de confiar en el contenido:

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));
}

Interpreta el JSON solo después de que la verificación sea correcta, y haz que tu manejador sea idempotente por si un evento llega más de una vez.

Errores y límites de solicitudes

Cualquier respuesta distinta de 2xx incluye un cuerpo JSON con un código error estable sobre el que puedes ramificar tu lógica y un message legible. Los códigos de estado que verás son 400 (parámetros no válidos), 401 (clave ausente o no válida), 403 (cuenta no lista o API no habilitada), 404 (no encontrado) y 429 (límite de solicitudes superado).

Los límites se cuentan por clave de API:

Si recibes un 429, espera y vuelve a intentarlo con retroceso exponencial.

Consejos de diseño para una integración fiable

• Guarda el id de la tarjeta, no su número. Pide los datos cuando los necesites.
• Usa metadata y label para vincular las tarjetas con tus propios registros, como un ID de cliente o una campaña.
• Prefiere los webhooks a las consultas periódicas para transacciones y desafíos 3D Secure.
• Deja un margen de saldo en las tarjetas que pagan cargos recurrentes, o usa auto_freeze_at y fund para gestionar los saldos automáticamente.
• Ten en cuenta los límites. Los límites del plan de la cuenta siguen aplicándose: el plan Virtual permite $5,000 por transacción y $20,000 por mes, mientras que el plan Platinum, que se desbloquea con un solo depósito de $300 o más, no tiene límites de gasto.

Si gestionas tarjetas para un equipo en lugar de escribir código, consulta tarjetas virtuales para equipos. Para casos de uso con cuentas publicitarias, lee tarjetas virtuales para anuncios. ¿Listo para empezar? Crea una cuenta.

Preguntas frecuentes

¿Qué es una API de tarjetas virtuales?

Es una interfaz que permite a un software crear y gestionar tarjetas de pago automáticamente. En USDT Crypto Card, es una API REST que usa JSON sobre HTTPS y se autentica con una clave secreta sk_live_.

¿Hay sandbox o SDK?

No. No hay entorno sandbox ni paquetes SDK oficiales. Llamas a la API REST directamente con cualquier cliente HTTP, y todas las llamadas son reales, así que haz pruebas con montos pequeños.

¿Por qué mi nueva clave de API devuelve 403?

La cuenta todavía no está lista. onboarding_incomplete significa que aún tienes que confirmar tu correo y hacer un primer depósito. api_not_enabled significa que el soporte todavía tiene que activar el acceso a la API.

¿Cómo se protegen los webhooks?

Cada envío se firma con HMAC-SHA256 usando el secreto de tu endpoint. Vuelve a calcular la firma sobre el cuerpo sin procesar y compárala en tiempo constante antes de confiar en el contenido.

¿Las tarjetas por API cuestan lo mismo que las del panel?

Sí. Se aplican las mismas comisiones: $1 por tarjeta, $0.30 por transacción aprobada, recargas gratuitas desde tu saldo y una comisión de depósito del 2% por debajo de $300.