Tovanix
Tovanix

API de tarjeta virtual

Emite y administra tarjetas virtuales Visa / Mastercard en lote mediante API, fondeadas con USDT: pensadas para cobros de suscripciones, publicidad y compras transfronterizas.

  • Consulta de BIN: BIN disponibles, regiones admitidas y rangos de límites
  • Emisión y recarga: crea tarjetas sobre el BIN elegido y recárgalas cuando lo necesites
  • Gestión de tarjetas: congelar, descongelar, cerrar y obtener los datos de la tarjeta de forma segura
  • Transacciones y webhooks: historial por transacción más eventos en tiempo real de autorización y liquidación

Resumen

La API abierta de tarjeta virtual te permite abrir tarjetas, listar BIN, leer los detalles de la tarjeta, obtener códigos OTP 3DS, consultar transacciones, recargar y cancelar; además de leer el saldo USD de tu cuenta y obtener una dirección fija de depósito TRON dedicada. Todos los endpoints devuelven una estructura JSON unificada (code/message/data; code=0 significa éxito).

URL base = la dirección de tu gateway (el origen de este sitio). Los endpoints de tarjeta llevan el prefijo /api/v1/vcard; los de cuenta, /api/v1/account.

Todos los montos están en USD; la apertura y la recarga se deducen del saldo USD de tu plataforma (solo pago con saldo). Si el saldo es insuficiente se devuelve un error.

Autenticación y firma

Los endpoints de lectura (BIN, lista de tarjetas, transacciones, órdenes, saldo, dirección de depósito) aceptan las dos claves en texto plano. Los endpoints que mueven fondos o devuelven datos sensibles requieren además firma HMAC + timestamp + nonce como protección contra repetición: abrir, recargar, cancelar, devolver saldo, congelar/descongelar, y también los datos completos de la tarjeta (details) y el código 3DS (code). Así, una clave filtrada por sí sola no puede mover fondos ni leer datos sensibles de la tarjeta.

Inicia sesión en la consola → Herramientas y ajustes → Gestión de API → Crear clave; copia la clave API y la Secret Key (la Secret solo se muestra una vez).

Abrir, recargar, cancelar, devolver saldo, congelar/descongelar, los datos completos de la tarjeta (número y CVV) y el código 3DS solo aceptan solicitudes firmadas; con las claves en texto plano se devuelve 401. Los demás endpoints de lectura no requieren firma.

Saldo de la cuenta

GET /api/v1/account/balance

Lee el saldo USD actual de la cuenta, incluyendo en la medida de lo posible la dirección fija de depósito TRON dedicada (deposit_address es null si el pool de direcciones no está disponible temporalmente; el saldo se devuelve de todos modos).

Dirección fija TRON

GET /api/v1/account/deposit-address

Obtén/asigna tu dirección fija de depósito TRON dedicada (USDT/TRX·TRC20). No se necesita orden: cualquier monto enviado se convierte automáticamente a USD y se acredita, ideal para recargas automatizadas vía API. Una vez asignada, la dirección se mantiene fija.

Campos de la respuesta

Envía USDT o TRX a esta dirección; en cuanto el escáner de bloques lo confirme, se convierte automáticamente a USD al tipo de cambio vigente y se acredita al saldo de tu plataforma, sin necesidad de callback.

Estado del servicio

GET /api/v1/vcard/info

Devuelve si el servicio de tarjeta virtual está activado y el saldo USD actual de la cuenta.

Campos de la respuesta

Si no se puede consultar el saldo de la cuenta, el endpoint devuelve HTTP 503 en lugar de balance: 0. Ante un 503 reintenta más tarde y no lo interpretes como saldo cero.

BIN de tarjetas

GET /api/v1/vcard/bins

Devuelve la lista de BIN de tarjetas. Las comisiones son precios finales que incluyen el margen de la plataforma, calculados según el nivel de API que corresponde a tu consumo de los últimos 30 días (más gasto = tarifa más baja). can_open=false marca los BIN de solo recarga (solo tarjetas existentes; no se pueden abrir tarjetas nuevas).

Abrir tarjeta Firmado

POST /api/v1/vcard/cards

Crea una tarjeta nueva. El sistema deduce del saldo USD de tu cuenta (comisión de apertura + comisión de recarga + monto cargado en la tarjeta); la orden se procesa de forma asíncrona mediante una cola.

Campos de la respuesta

La apertura es asíncrona: cuando la respuesta devuelve order_id y status=queued, consulta el endpoint de detalle de la orden hasta que llegue a completed. Los fallos se reembolsan automáticamente al saldo de tu cuenta.

Cuando una solicitud agota el tiempo de espera o se corta la conexión, es posible que el cobro ya se haya hecho. No reintentes con un número nuevo: reenvía con el mismo out_trade_no (el pedido existente se devuelve tal cual y no se cobra otra vez) o consulta el resultado con GET /api/v1/vcard/orders/by-trade-no/:out_trade_no. Las solicitudes sin out_trade_no no tienen esta protección, y un reintento puede generar un segundo cobro.

Lista de tarjetas

GET /api/v1/vcard/cards

Devuelve todas las tarjetas de tu cuenta (número enmascarado con los últimos 4 dígitos, saldo, estado de uso, estado de cancelación).

Campos de la respuesta

La lista de tarjetas devuelve solo los campos de la tabla anterior. can_return y fee_return se devuelven solo para algunos BIN; si faltan, considera que la tarjeta no admite la devolución de saldo.

Detalles de la tarjeta Firmado

GET /api/v1/vcard/cards/:id/details

Devuelve los datos sensibles en texto plano de una tarjeta: número completo, CVV, vencimiento y titular. Solo puedes consultar tus propias tarjetas.

Campos de la respuesta

Nota: la tabla anterior enumera los campos que la plataforma garantiza; la respuesta puede incluir otros campos, según lo que se devuelva realmente.

Este endpoint devuelve el número completo de la tarjeta y el CVV: llámalo solo desde un servidor de confianza y nunca lo expongas en el frontend ni en los registros.

Transacciones

GET /api/v1/vcard/cards/:id/transactions

Devuelve los registros de transacciones/estado de cuenta de la tarjeta (consumo, recarga, etc.); cada consulta sincroniza en tiempo real los movimientos más recientes.

Campos de la respuesta

Nota: la tabla anterior enumera los campos que la plataforma garantiza; la respuesta puede incluir otros campos, según lo que se devuelva realmente.

Código OTP Firmado

GET /api/v1/vcard/cards/:id/code

Obtén el código OTP 3DS más reciente de la tarjeta, usado para la verificación del pago.

Recargar Firmado

POST /api/v1/vcard/cards/:id/recharge

Recarga una tarjeta existente. Se deduce del saldo USD de la cuenta (monto de recarga + comisión de recarga); se procesa de forma asíncrona mediante una cola.

Campos de la respuesta

Cuando una solicitud agota el tiempo de espera o se corta la conexión, es posible que el cobro ya se haya hecho. No reintentes con un número nuevo: reenvía con el mismo out_trade_no (el pedido existente se devuelve tal cual y no se cobra otra vez) o consulta el resultado con GET /api/v1/vcard/orders/by-trade-no/:out_trade_no. Las solicitudes sin out_trade_no no tienen esta protección, y un reintento puede generar un segundo cobro.

Cancelar Firmado

POST /api/v1/vcard/cards/:id/cancel

Envía la cancelación de una tarjeta. La cancelación es asíncrona: cuando el banco la confirma (puede tardar días), el saldo restante de la tarjeta se reembolsa automáticamente al saldo de tu cuenta.

Devolución de saldo Firmado

POST /api/v1/vcard/cards/:id/return

Devuelve el saldo restante de la tarjeta al saldo de tu cuenta sin cancelar la tarjeta. La comisión se deduce del monto devuelto y el neto se acredita automáticamente. Solo se admite en algunos BIN: se puede llamar cuando can_return es true en la lista de tarjetas; fee_return es la comisión de devolución de ese BIN.

Solo se acepta una devolución por tarjeta a la vez. Si envías otra mientras la anterior sigue en curso, se devuelve 400: espera a que la orden llegue a un estado terminal en lugar de reintentar la misma solicitud.

Congelar / Descongelar Firmado

POST /api/v1/vcard/cards/:id/freeze

Congela o descongela una tarjeta. Cada operación cobra una pequeña comisión (ver status_fee en la lista de tarjetas). Solo se puede llamar cuando can_freeze es true; devuelve 400 si la tarjeta ya está en el estado objetivo o si una operación anterior sigue en curso.

Recarga automática (reglas de saldo) Firmado

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

Recarga una tarjeta automáticamente cuando su saldo baja de un monto fijado, o solo envía un aviso. Cada tarjeta tiene una regla; PUT la crea o la reemplaza. Las recargas automáticas usan la misma vía de cobro que las manuales (mismos límites y comisiones) y se ejecutan cuando cambia el saldo o en una revisión cada minuto.

Límites de seguridad: son obligatorios un número diario de recargas (1–10, en la zona horaria de tu cuenta) y un tope mensual de monto. La regla se pausa sola y te avisa si la tarjeta está congelada o en cierre, si el emisor rechaza por fraude, si se rechazan 3 transacciones seguidas o si tu saldo no alcanza 3 veces seguidas. Llama a resume para reactivarla (las reglas pausadas por la plataforma no las puedes reactivar tú).

Las claves de API con límite de gasto diario no pueden crear ni reactivar la recarga automática (403, código 4035): la plataforma cobra las recargas automáticas en segundo plano, fuera del límite de la clave. Las reglas de solo aviso no se ven afectadas.

Suscripciones

GET /api/v1/vcard/subscriptions

Cobros recurrentes detectados en las transacciones de tus tarjetas activas (solo lectura, calculado al momento): los cobros repetidos del mismo comercio con aproximadamente una semana, un mes o un año de diferencia cuentan como suscripción. Para detener una, congela o cierra la tarjeta.

Comercios permitidos Firmado

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 con qué comercios se puede usar una tarjeta. Si aparece una transacción de otro comercio, la tarjeta se congela automáticamente (una comisión de congelación) o solo se te avisa. Solo se revisan las transacciones posteriores a guardar la configuración, y la congelación es posterior: la primera transacción fuera de la lista ya fue autorizada.

Grupos de tarjetas

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

Organiza las tarjetas en grupos, cada uno con un presupuesto mensual opcional: recibes un aviso al llegar al 80% y otro al superarlo; las transacciones nunca se bloquean. Una tarjeta está en un solo grupo; group_id 0 la quita de su grupo. Hasta 20 grupos.

Extracto mensual

GET /api/v1/vcard/bill/export

Las transacciones de tarjeta de un mes, opcionalmente de una sola tarjeta o un grupo, de la más antigua a la más reciente. Solo incluye las transacciones del período en que tuviste la tarjeta; si la consulta superara 20.000 filas recibes 400: exporta por tarjeta o por grupo.

Lista de órdenes

GET /api/v1/vcard/orders

Lista paginada de tus órdenes de apertura/recarga/cancelación.

Detalle de la orden

GET /api/v1/vcard/orders/:id

Consulta el progreso de una orden; se usa para sondear el resultado tras abrir/recargar.

Devuelve un único objeto de orden con exactamente los mismos campos que el objeto de orden de "Consultar órdenes".

Consultar un pedido por tu propio número

GET /api/v1/vcard/orders/by-trade-no/:out_trade_no

Consulta un pedido por el out_trade_no enviado al emitir o recargar una tarjeta. La respuesta es la misma que en «Detalle de la orden». Devuelve 404 si el número no existe.

Actualizar observación

PUT /api/v1/vcard/cards/:id/remark

Establece una observación personalizada en una tarjeta (máx. 60 caracteres).

Push por Webhook

Cuando ocurren eventos (tarjeta abierta / recargada / cancelada, nueva transacción, nuevo código 3DS), la plataforma los envía a tu endpoint mediante HTTP POST (JSON), sin necesidad de polling. Configúralo en Consola → Tarjeta virtual → Integración API (interruptor de activación + URL del endpoint + Secret de firma + eventos suscritos; dejar los eventos sin marcar = suscribirse a todos).

Contrato de entrega: el endpoint debe ser una URL https accesible públicamente; la carga es un objeto JSON plano con todos los valores como cadenas; responder 2xx marca la entrega como exitosa; de lo contrario, la plataforma reintenta con retroceso exponencial 30 s → 1 min → 2 min → 5 min → 10 min, hasta 10 intentos. Los reintentos llevan el mismo notify_id: deduplica por él para garantizar idempotencia.

Campos comunes (presentes en todos los eventos; los campos específicos de cada evento se listan más abajo):

Verificación: toma todos los campos no vacíos excepto "sign", ordénalos por clave ASC, únelos como k=v&k2=v2, calcula HMAC-SHA256 (hex, minúsculas) con tu Secret y compáralo con el sign de la carga; exige además que sign_ts esté dentro de ±5 minutos y que el nonce no se haya visto antes. Rechaza con 401 si falla cualquier comprobación.

Eventos y sus campos específicos:

Preguntas frecuentes

¿Cuándo puedo usar la tarjeta y dónde se acepta?

La emisión devuelve los datos de la tarjeta en segundos y funciona de inmediato en cualquier sitio que acepte pagos en línea con Visa / Mastercard: habitualmente suscripciones a servicios de IA, recargas en plataformas publicitarias y comercio electrónico transfronterizo.

¿Cómo depuro una transacción rechazada?

Consulta en el endpoint de historial de transacciones el código de motivo del rechazo de esa autorización; lo más común es saldo insuficiente, una categoría de comercio restringida o un bloqueo del control de riesgos. Los eventos de autorización y liquidación también se envían por webhook para la conciliación.

Páginas relacionadas: Tarjetas virtuales · Documentación de la API · Pagos cripto multicadena

Cargando…