> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluz.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`](/features/get-card-offers) 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:

```mermaid theme={null}
stateDiagram-v2
    [*] --> ACTIVE: createVirtualCard
    ACTIVE --> LOCKED: lockVirtualCard
    LOCKED --> ACTIVE: unlockVirtualCard
    ACTIVE --> CLOSED_EXPIRED: lockDate reached, or manually cancelled
    CLOSED_EXPIRED --> [*]
```

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](/features/edit-virtual-card) 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:

```bash theme={null}
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](/get-started/refresh-expired-access-token) 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:

1. La **cuenta de gasto** designada (`userCashBalanceId`)
2. **Saldo prepago (tarjeta de regalo)** — a menos que `usePrepaymentBalance: false`
3. **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](/features/create-card).

## 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](/features/get-card-offers)                     |
| Pre-guardar una dirección de facturación   | Mutation | `CREATE_VIRTUALCARD`                    | [Agregar Dirección de Tarjeta Virtual](/features/add-billing-address)               |
| Emitir una tarjeta                         | Mutation | `CREATE_VIRTUALCARD`                    | [Crear Tarjeta Virtual](/features/create-card)                                      |
| Recuperar PAN, CVV, vencimiento            | Mutation | `REVEAL_VIRTUALCARD`                    | [Revelar Tarjeta Virtual](/recipes/reveal-virtual-card)                             |
| Actualizar límite, alias, fecha de bloqueo | Mutation | `EDIT_VIRTUALCARD`                      | [Editar Tarjeta Virtual](/features/edit-virtual-card)                               |
| Bloquear temporalmente el gasto            | Mutation | `EDIT_VIRTUALCARD`                      | [Bloquear Tarjeta Virtual](/features/lock-virtual-card)                             |
| Rehabilitar una tarjeta bloqueada          | Mutation | `EDIT_VIRTUALCARD`                      | [Desbloquear Tarjeta Virtual](/features/unlock-virtual-card)                        |
| Consultar saldo restante (lote)            | Query    | `REVEAL_VIRTUALCARD` + `PCI_COMPLIANCE` | [Obtener Saldo de Tarjeta Virtual](/recipes/get-virtual-card-balance)               |
| Ver historial de transacciones             | Query    | `CREATE_VIRTUALCARD`                    | [Obtener Transacciones de Tarjeta Virtual](/features/get-virtual-card-transactions) |
| Emitir tarjetas en lote (asíncrono)        | Mutation | `CREATE_VIRTUALCARD`                    | [Operaciones en Lote](/features/create-bulk-order)                                  |
| Distribuir tarjetas vía enlace hospedado   | Mutation | `CREATE_SHARE_LINK`                     | [Enviar Enlaces Hospedados con Tarjetas Virtuales](/features/send-cards)            |
| Establecer un PIN                          | Mutation | `EDIT_VIRTUALCARD`                      | [Establecer PIN de Tarjeta Virtual](/set-virtual-card-pin)                          |
| Agregar a Apple Pay / Google Pay           | Mutation | —                                       | [Aprovisionamiento por Push a Billetera Digital](/digital-wallet-push-provisioning) |
| Aplicar ofertas específicas del comercio   | —        | —                                       | [Ofertas Vinculadas a Tarjeta](/features/card-linked-offers)                        |
| Referencia de errores                      | —        | —                                       | [Códigos de Error de Tarjeta Virtual](/features/virtual-card-error-codes)           |

## Próximos pasos

<Card title="Crea tu primera tarjeta virtual" icon="credit-card" horizontal href="/features/create-card">
  El contrato completo de `createVirtualCard` — entradas, opciones de fondeo, controles de gasto y ejemplos.
</Card>