Descripción general

Las Tarjetas Virtuales Pre-Fondeadas son tarjetas con marca de red (Visa / Mastercard) emitidas al instante mediante la API de Fluz. Ganan cashback en cada comercio que acepte la red, y se pueden combinar con ruteo de tarjetas de regalo en más de 400 marcas para obtener recompensas aún mayores.

¿Qué es una Tarjeta Virtual de Fluz?

Una Tarjeta Virtual Pre-Fondeada de Fluz es una tarjeta con marca de red, emitida al instante, que vive completamente en software. A diferencia de una tarjeta física:

Sin plástico, sin envíos: la tarjeta está disponible en el momento en que se resuelve createVirtualCard.
Pre-fondeada: el límite de gasto se reserva al momento de la creación desde una Billetera de Fluz, saldo de tarjeta de regalo, saldo de recompensas o una cuenta bancaria vinculada.
Con alcance definido: cada tarjeta tiene su propio límite de gasto, duración, fecha de bloqueo y un indicador opcional de un solo uso, para que controles exactamente cuánto y por cuánto tiempo se puede cobrar.
Aceptación total en la red: emitida sobre rieles de Mastercard (débito o prepago) o Visa, usable en cualquier lugar donde esas redes sean aceptadas en línea o en tienda.

Las tarjetas ganan un cashback base en todo el gasto mediante la economía de interchange. En comercios compatibles, las ofertas vinculadas a la tarjeta pueden sumar retornos adicionales.

Tipos de tarjeta

Tipo	Descripción
Tarjeta Virtual Estándar	Funciona en todos los comercios de la red de la tarjeta
Tarjeta Virtual Bloqueada a Marca	Restringida a un comercio específico; útil para programas de incentivos dirigidos o controles de gasto

Usa getVirtualCardOffers para enumerar todos los programas disponibles en tu cuenta, incluido el tipo de red (Mastercard / Visa), tipo de tarjeta (débito / prepago), banco emisor y límites de gasto por programa.

Ciclo de vida de la tarjeta

Una tarjeta pasa por los siguientes estados: Una tarjeta configurada con lockCardNextUse: true pasa automáticamente de ACTIVE a LOCKED después de su primera autorización exitosa, sin necesidad de una llamada adicional a la API. Consulta Editar Tarjeta Virtual para saber cómo modificar esta configuración después de la creación. LOCKED no es un valor de status: una tarjeta bloqueada aún reporta status: ACTIVE. Lee locked desde Obtener Saldo de Tarjeta Virtual para saber si una tarjeta puede gastar.

Alcances requeridos

Todas las operaciones de tarjetas virtuales requieren un User Access Token generado con los alcances apropiados. Los tres alcances principales son:

Alcance	Usado por
`CREATE_VIRTUALCARD`	Crear tarjetas, obtener ofertas, consultar saldos, obtener transacciones
`REVEAL_VIRTUALCARD`	Revelar PAN, CVV y vencimiento; también requerido para `getVirtualCardBalance`. Devolver datos crudos de la tarjeta también requiere `PCI_COMPLIANCE` en tu aplicación; consulta Revelar datos de la tarjeta
`EDIT_VIRTUALCARD`	Editar, bloquear, desbloquear, configurar PIN

Genera un token con los tres alcances antes de llamar a cualquier endpoint de tarjeta virtual:

curl -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
  -H "Authorization: Basic <YOUR_SANDBOX_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation generateUserAccessToken($userId: UUID!, $accountId: UUID!, $scopes: [ScopeType!]!) { generateUserAccessToken(userId: $userId, accountId: $accountId, scopes: $scopes) { token scopes } }",
    "variables": {
      "userId": "<YOUR_SANDBOX_USER_ID>",
      "accountId": "<YOUR_ACCOUNT_ID>",
      "scopes": ["CREATE_VIRTUALCARD", "REVEAL_VIRTUALCARD", "EDIT_VIRTUALCARD"]
    }
  }'

Pasa el token devuelto como Authorization: Bearer <token> en todas las llamadas posteriores. Consulta Actualizar un User Access Token vencido cuando recibas un 401.

Revelar datos de la tarjeta

Hay dos maneras de poner el PAN, vencimiento y CVV de una tarjeta frente a un usuario, y tienen implicaciones de cumplimiento muy diferentes.

Ruta	Dónde se puede leer la data	Qué se requiere
Revelado de Tarjeta con Elementos Seguros	Un frame alojado por Fluz, montado en línea en tu propia página	Un token de cliente generado a partir de tu token de acceso existente. Sin concesión de `PCI_COMPLIANCE`: tus servidores y el JavaScript de tu página nunca ven los datos
`revealVirtualCardByVirtualCardId`	Tu propio servidor, en la respuesta de la API	`REVEAL_VIRTUALCARD` + `PCI_COMPLIANCE`. Concedido a solicitud en tu propia cuenta; requiere una certificación PCI DSS en cuentas pertenecientes a otras personas

Recurre a la mutación de la API cuando realmente necesites los números del lado del servidor, por ejemplo para enviarlos a otro procesador. Si una persona los va a leer en pantalla, Elementos Seguros es el camino más corto.

Cómo funciona el fondeo

Cuando se cobra una tarjeta, Fluz extrae fondos en este orden de prioridad por defecto:

La cuenta de gasto designada (userCashBalanceId)
Saldo prepago (tarjeta de regalo), a menos que usePrepaymentBalance: false
Saldo de recompensas, a menos que useRewardsBalance: false

También puedes fondear directamente desde una cuenta bancaria vinculada configurando primaryFundingSource: BANK_ACCOUNT. Los detalles completos de entrada y ejemplos están en Crear Tarjeta Virtual.

Duraciones del límite de gasto

El spendLimit que configures aplica según el spendLimitDuration elegido:

Duración	Comportamiento
`LIFETIME`	Aplica durante toda la vida útil de la tarjeta (predeterminado)
`DAILY`	Se restablece cada día calendario
`WEEKLY`	Se restablece semanalmente
`MONTHLY`	Se restablece el primer día de cada mes

Solo se te cobra el monto realmente gastado: el límite de gasto es un techo de autorización, no un cargo por adelantado. El saldo no utilizado permanece en tu billetera.

Tarjetas de un solo uso

Configura lockCardNextUse: true al crear (o actualízalo mediante editVirtualCard) para bloquear la tarjeta automáticamente después de su primera autorización. Este es el patrón recomendado para:

Pagos únicos a proveedores
Desembolsos de una sola transacción
Flujos de pago agénticos donde la tarjeta debe consumirse tras un uso

Todas las operaciones de Tarjeta Virtual

Operación	Tipo	Alcance(s)	Página
Descubrir programas disponibles	Query	`CREATE_VIRTUALCARD`	Obtener Ofertas de Tarjeta Virtual
Pre-guardar una dirección de facturación	Mutation	`CREATE_VIRTUALCARD`	Agregar Dirección de Tarjeta Virtual
Emitir una tarjeta	Mutation	`CREATE_VIRTUALCARD`	Crear Tarjeta Virtual
Recuperar PAN, CVV, vencimiento (servidor)	Mutation	`REVEAL_VIRTUALCARD` + `PCI_COMPLIANCE`	Revelar Tarjeta Virtual
Mostrar PAN, CVV, vencimiento a un usuario	SDK	—	Revelado de Tarjeta con Elementos Seguros
Actualizar límite, apodo, fecha de bloqueo	Mutation	`EDIT_VIRTUALCARD`	Editar Tarjeta Virtual
Bloquear temporalmente el gasto	Mutation	`EDIT_VIRTUALCARD`	Bloquear Tarjeta Virtual
Rehabilitar una tarjeta bloqueada	Mutation	`EDIT_VIRTUALCARD`	Desbloquear Tarjeta Virtual
Consultar saldo, estado y bloqueo (lote)	Query	`REVEAL_VIRTUALCARD` + `PCI_COMPLIANCE`	Obtener Saldo de Tarjeta Virtual
Ver historial de transacciones	Query	`CREATE_VIRTUALCARD`	Obtener Transacciones de Tarjeta Virtual
Emitir tarjetas en lote (asíncrono)	Mutation	`CREATE_VIRTUALCARD`	Operaciones en Lote
Distribuir tarjetas vía enlace alojado	Mutation	`CREATE_SHARE_LINK`	Enviar Enlaces Alojados con Tarjetas Virtuales
Configurar un PIN	Mutation	`EDIT_VIRTUALCARD`	Configurar PIN de Tarjeta Virtual
Enviar a Apple Pay / Google Pay	Mutation	—	Aprovisionamiento Push a Billeteras Digitales
Aplicar ofertas específicas por comercio	—	—	Ofertas Vinculadas a Tarjeta
Referencia de errores	—	—	Códigos de Error de Tarjeta Virtual

Próximos pasos

Crea tu primera tarjeta virtual

El contrato completo de createVirtualCard: entradas, opciones de fondeo, controles de gasto y ejemplos.

​¿Qué es una Tarjeta Virtual de Fluz?

​Tipos de tarjeta

​Ciclo de vida de la tarjeta

​Alcances requeridos

​Revelar datos de la tarjeta

​Cómo funciona el fondeo

​Duraciones del límite de gasto

​Tarjetas de un solo uso

​Todas las operaciones de Tarjeta Virtual

​Próximos pasos