Descripción general

Las Tarjetas Virtuales Prepagadas son tarjetas con marca de red (Visa / Mastercard) emitidas al instante a través del API de Fluz. Obtienen cashback en cada comercio que acepte la red, y pueden combinarse con enrutamiento 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 Prepagada de Fluz es una tarjeta con marca de red, emitida al instante y que existe completamente en software. A diferencia de una tarjeta física:

Sin plástico, sin envío — la tarjeta está disponible en el momento en que createVirtualCard se resuelve.
Prepagada — el límite de gasto se reserva en el 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 una bandera opcional de un solo uso, para que controles exactamente cuánto se puede cobrar y por cuánto tiempo.
Aceptación total de 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 tiendas físicas.

Las tarjetas ganan un cashback base en todo el gasto mediante economía de intercambio. En los comercios compatibles, las ofertas vinculadas a tarjeta pueden sumar rendimientos 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 por 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 para tu cuenta, incluyendo 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 transiciona automáticamente de ACTIVE a LOCKED después de su primera autorización exitosa — no se requiere una llamada adicional al API. Consulta Editar Tarjeta Virtual para saber cómo modificar esta configuración después de la creación.

Alcances requeridos

Todas las operaciones de tarjeta virtual requieren un Token de Acceso de Usuario 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 se requiere para `getVirtualCardBalance` junto con `PCI_COMPLIANCE`
`EDIT_VIRTUALCARD`	Editar, bloquear, desbloquear, establecer PIN

Genera un token con los tres alcances antes de llamar 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 subsiguientes. Consulta Actualizar un Token de Acceso de Usuario Vencido cuando recibas un 401.

Cómo funcionan los fondos

Cuando se carga una tarjeta, Fluz toma fondos en este orden de prioridad de manera predeterminada:

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 estableces 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 por el monto realmente gastado — el límite de gasto es un tope de autorización, no un cargo previo. 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 a proveedores por única vez
Desembolsos de una sola transacción
Flujos de pago agénticos donde una tarjeta debe consumirse después de un uso

Todas las operaciones con Tarjetas Virtuales

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	Mutation	`REVEAL_VIRTUALCARD`	Revelar Tarjeta Virtual
Actualizar límite, alias, 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 restante (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 hospedado	Mutation	`CREATE_SHARE_LINK`	Enviar Enlaces Hospedados con Tarjetas Virtuales
Establecer un PIN	Mutation	`EDIT_VIRTUALCARD`	Establecer PIN de Tarjeta Virtual
Agregar a Apple Pay / Google Pay	Mutation	—	Aprovisionamiento por Push a Billetera Digital
Aplicar ofertas específicas del 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

​Cómo funcionan los fondos

​Duraciones del límite de gasto

​Tarjetas de un solo uso

​Todas las operaciones con Tarjetas Virtuales

​Próximos pasos