Requisitos previos
- Una cuenta de Fluz: crearás credenciales de API de staging y generarás un token de acceso en los Pasos 1–2 a continuación.
- Las solicitudes van al endpoint GraphQL del sandbox. Nada aquí cobra una tarjeta real: consulta Entorno de Staging vs. Live.
- Cada mutación necesita un
idempotencyKeyúnico (un UUID generado por el cliente) para que una solicitud solo se procese una vez: consulta Idempotencia.
Antes de comenzar
Cada llamada es una solicitudPOST a un único endpoint de GraphQL. Generar tu token (Paso 2) se autentica con tu API Key; todas las demás llamadas se autentican con tu token bearer:
El flujo completo
Regístrate y registra una app
Crea una cuenta de Fluz en fluz.app, luego abre la Consola de Desarrolladores y crea una nueva aplicación Staging. Cuando aparezcan las credenciales, copia tu API Key, User ID y Account ID.Guía completa: Prepara tus cuentas.
Intercambia credenciales por un token de acceso
Genera un token de acceso de usuario de corta duración y con alcances específicos usando tu API Key. Esta llamada va al mismo endpoint de GraphQL, autorizada con Guarda el
Authorization: Basic <YOUR_API_KEY>; todas las llamadas posteriores usan el token devuelto como credencial Bearer.token devuelto y envíalo como Authorization: Bearer <token> en cada solicitud a continuación. Los tokens son de corta duración: genéralos del lado del servidor y genera uno nuevo con la misma mutación cuando uno expire (consulta Actualizar un token de acceso vencido). Detalles completos: Credenciales de API.Fondea tu saldo de Fluz
Las tarjetas virtuales se fondean desde tu cuenta cuando se usan, por defecto desde tu saldo de Fluz (
FLUZ_BALANCE). Asegúrate de que haya suficiente saldo disponible para cubrir el límite de gasto que planeas establecer. Puedes fondear de dos maneras:- Manualmente, vía el sitio web de Fluz en sandbox.
- Programáticamente, vía la mutación
depositCashBalance.
Depositar vía API (depositCashBalance)
Depositar vía API (depositCashBalance)
Recupera un ID de fuente de fondos con El Quickstart de tarjeta de regalo recorre este paso en detalle completo, incluyendo cómo recuperar IDs de métodos de pago con
getWallet, luego deposita:getWallet.¿Prefieres fondear tarjetas desde una cuenta bancaria vinculada? Establece
primaryFundingSource: BANK_ACCOUNT al crear la tarjeta (Paso 5) y pasa el bankAccountId, sin necesidad de saldo prefondeado.Explora programas de tarjetas y elige una oferta
Cada tarjeta virtual se emite contra un programa de tarjetas (una “oferta”): el programa determina la red, el banco emisor, la tasa de recompensa y los límites de gasto dentro de los que debe mantenerse tu tarjeta. Obtén los programas disponibles para tu cuenta con Las ofertas se ordenan por
getVirtualCardOffers.rewardValue, por lo que los programas con mayor ganancia aparecen primero. Puedes filtrar con el input opcional: cardType (DEBIT / PREPAID), cardNetwork (MASTERCARD / VISA) y cardBrandLocked. Referencia completa: Obtener ofertas de tarjetas virtuales.En el sandbox, estos programas de prueba siempre están disponibles:¿No estás seguro de qué programa elegir? Virtual Card es el programa de propósito general para gastar en cualquier lugar: la opción predeterminada correcta para este Quickstart. Las tarjetas Brand Locked solo funcionan en un único comercio, las Single Load se fondean una vez y se consumen, y las Reloadable pueden recargarse después de su creación. Consulta Ofertas de tarjetas virtuales de prueba para un desglose completo.
Guarda el
offerId que quieres y toma nota de sus programLimits: el spendLimit que establezcas en el siguiente paso debe ajustarse al límite del programa para la duración elegida.Crea la tarjeta, configurada para tu caso de uso
Emite la tarjeta con Las tres ejecutan la misma mutación:
createVirtualCard. La configuración del input es lo que convierte una tarjeta genérica en una diseñada para un propósito: elige el patrón que coincida con lo que estás creando:- Compra única
- Suscripción con tope mensual
- Tarjeta con presupuesto y tiempo definido
Una tarjeta para exactamente una transacción. Establece
spendLimit al monto de la compra y lockCardNextUse: true para que la tarjeta se bloquee después de su primera autorización: nada más podrá cobrarse en ella.Variables
La configuración, de un vistazo
Float
requerido
El máximo que se puede cobrar a la tarjeta: solo se te cobra por lo que realmente se utiliza. Debe ajustarse al límite del programa para la duración elegida.
VirtualCardSpendLimitDuration
predeterminado:"LIFETIME"
Cómo se restablece el límite.
LIFETIME limita el gasto total; DAILY / WEEKLY / MONTHLY lo convierten en un presupuesto rotativo, la opción correcta para suscripciones y asignaciones de equipo.Boolean
predeterminado:"false"
Bloquea la tarjeta después de su primer uso exitoso: el patrón de “tarjeta virtual de un solo uso” para pagos puntuales a proveedores.
String
predeterminado:"47 months from creation"
Fecha
yyyy-mm-dd en que la tarjeta se congela. Limita las tarjetas en el tiempo para un proyecto, viaje o período de contrato.VirtualCardFundingSource
predeterminado:"FLUZ_BALANCE"
De dónde se extrae el gasto.
FLUZ_BALANCE usa tu saldo prefondeado; BANK_ACCOUNT extrae de una cuenta vinculada (requiere bankAccountId).Boolean
predeterminado:"true"
De forma predeterminada, una tarjeta también puede extraer de saldos prepagados (tarjeta de regalo) y de recompensas. Establece ambos en
false para tarjetas solo en efectivo que extraen únicamente del userCashBalanceId especificado: lo más limpio para contabilidad.String
Metadatos de gasto opcionales adjuntos a la transacción resultante: las categorías se crean en el primer uso. Consulta Agregar detalles de gastos.
Dirección de facturación: si tu cuenta no tiene una registrada, pasa un
billingAddress (o un userAddressId guardado). Debe ser una dirección US real y entregable — sin apartados postales — o la creación fallará con VC-0025. Consulta Requisitos de formato de direcciones.Conserva el
virtualCardId de la respuesta: lo usarás para revelar la tarjeta a continuación. Si la creación falla, revisa Códigos de error de tarjetas virtuales.Revela los datos de la tarjeta
La respuesta de creación excluye deliberadamente los números sensibles. Recupera el PAN completo, CVV y vencimiento con Requiere el alcance
revealVirtualCardByVirtualCardId: esto es lo que tú (o tu usuario) ingresan en un checkout o agregan a una billetera móvil.REVEAL_VIRTUALCARD.Gasta y luego observa la actividad
Usa los datos revelados en cualquier lugar donde se acepte la red de la tarjeta, dentro de los límites que estableciste. Luego obtén la actividad de la tarjeta con Requiere los alcances
getVirtualCardTransactions para confirmar el cargo: la misma consulta alimenta tableros de gasto, conciliación y monitoreo de rechazos.PCI_COMPLIANCE y REVEAL_VIRTUALCARD. Omite virtualCardIds para obtener la actividad de todas las tarjetas de la cuenta y filtra por rango de fechas para vistas tipo estado de cuenta. Referencia completa: Obtener transacciones de tarjetas virtuales.¿Terminaste con la tarjeta? Bloquéala (lockVirtualCard)
¿Terminaste con la tarjeta? Bloquéala (lockVirtualCard)
Las tarjetas con Requiere el alcance
lockCardNextUse o una lockDate se gestionan solas. Para bloquear cualquier otra tarjeta bajo demanda:EDIT_VIRTUALCARD. El bloqueo es reversible: consulta Desbloquear tarjeta virtual.¡Listo! 🎉
Has emitido una tarjeta virtual diseñada para un trabajo específico: elegiste un programa, configuraste controles de gasto, revelaste la tarjeta y rastreaste su actividad. A partir de aquí, profundiza más:Editar, bloquear y administrar tarjetas
Cambia límites, apodos y fechas de bloqueo en tarjetas existentes.
Billeteras digitales y PIN
Envía tarjetas a Apple Pay / Google Wallet y configura PIN.
Emisión en lote
Crea hasta 10,000 tarjetas en una sola orden.
Enviar tarjetas a otros
Distribuye tarjetas a destinatarios por enlace, email o SMS.
¿Quieres saber más? Contáctanos en support@fluz.app para hablar con nuestros expertos o solicitar una demo.