Skip to main content
Este Quickstart te lleva desde una cuenta nueva de Fluz hasta una tarjeta virtual emitida y lista para gastar. Registrarás una app, generarás un token de acceso con alcances específicos, luego explorarás programas de tarjetas, crearás una tarjeta configurada para tu caso de uso, revelarás sus datos y observarás sus transacciones, todo en el sandbox, donde no se mueve dinero real.
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 solicitud POST 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:
Staging incluye programas de tarjetas de prueba listos para emitir, y tu cuenta de sandbox incluye una tarjeta bancaria de prueba preagregada para fondeo. Consulta Comercios de prueba y Tarjetas bancarias de prueba para ver el conjunto completo de datos del sandbox.

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 Authorization: Basic <YOUR_API_KEY>; todas las llamadas posteriores usan el token devuelto como credencial Bearer.
Guarda el 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.
Los alcances controlan lo que el token puede hacer: incluye solo lo que tu flujo necesita: MANAGE_PAYMENT para fondear tu saldo, CREATE_VIRTUALCARD para explorar programas y emitir tarjetas, REVEAL_VIRTUALCARD + PCI_COMPLIANCE para revelar tarjetas y obtener sus transacciones, y EDIT_VIRTUALCARD para bloquear, desbloquear o editar tarjetas más adelante.
Nunca expongas tu API Key en un navegador o cliente móvil. Genera tokens del lado del servidor y reenvía únicamente el token.

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:
Recupera un ID de fuente de fondos con getWallet, luego deposita:
El Quickstart de tarjeta de regalo recorre este paso en detalle completo, incluyendo cómo recuperar IDs de métodos de pago con 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 getVirtualCardOffers.
Las ofertas se ordenan por 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 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:
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
Las tres ejecutan la misma mutación:

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 revealVirtualCardByVirtualCardId: esto es lo que tú (o tu usuario) ingresan en un checkout o agregan a una billetera móvil.
Requiere el alcance REVEAL_VIRTUALCARD.
La respuesta contiene el número completo de la tarjeta y el CVV en texto plano. Trátalo como datos sensibles del titular de la tarjeta: transmítelos solo mediante TLS, nunca los registres en logs y muéstralos únicamente al usuario autorizado.
La mayoría de los checkouts en línea no necesitan PIN, pero si tu caso de uso lo requiere (o quieres pago sin contacto), consulta Configurar PIN de tarjeta virtual y Provisionamiento por push a billeteras digitales para agregar la tarjeta a Apple Pay o Google Pay en un toque.

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 getVirtualCardTransactions para confirmar el cargo: la misma consulta alimenta tableros de gasto, conciliación y monitoreo de rechazos.
Requiere los alcances 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.
Las tarjetas con lockCardNextUse o una lockDate se gestionan solas. Para bloquear cualquier otra tarjeta bajo demanda:
Requiere el alcance 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.