Tu primera compra con tarjeta virtual

Este Quickstart te lleva desde una cuenta nueva de Fluz hasta una tarjeta virtual emitida y lista para gastar. Registrarás una app, acuñarás un token de acceso con alcance, luego explorarás programas de tarjetas, crearás una tarjeta configurada para tu caso de uso, revelarás sus detalles 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 acuñarás un token de acceso en los Pasos 1–2 más abajo.
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

Excepto para acuñar tu token (Paso 2), cada llamada es una solicitud POST a un único endpoint GraphQL, autenticada con tu bearer token:

POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql

Authorization: Bearer <YOUR_USER_ACCESS_TOKEN>
Content-Type: application/json

curl -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
  -H "Authorization: Bearer <YOUR_USER_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query GetVirtualCardOffers { getVirtualCardOffers { offerId programName rewardValue } }"
  }'

Staging viene con programas de tarjeta 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 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 clientId y clientSecret — el secret se muestra solo una vez.Guía completa: Prepara tus cuentas.

Intercambia credenciales por un token de acceso

Acuña un token de acceso de usuario de corta duración y con alcance a partir de las credenciales de tu app. Esta llamada va al servicio OAuth; cada llamada posterior usa el token devuelto como credencial Bearer.

    curl -X POST https://oauth-service.fluzapp.com/graphql \
      -H "Content-Type: application/json" \
      -d '{
        "query": "mutation ($clientId: String!, $clientSecret: String!, $scopes: [Scope!]!) { generateUserAccessToken(clientId: $clientId, clientSecret: $clientSecret, scopes: $scopes) { accessToken expiresIn scopes } }",
        "variables": {
          "clientId": "<APPLICATION_CLIENT_ID>",
          "clientSecret": "<APPLICATION_CLIENT_SECRET>",
          "scopes": ["MANAGE_PAYMENT", "CREATE_VIRTUALCARD", "EDIT_VIRTUALCARD", "REVEAL_VIRTUALCARD", "PCI_COMPLIANCE"]
        }
      }'

    {
      "data": {
        "generateUserAccessToken": {
          "accessToken": "eyJhbGciOi...",
          "expiresIn": 3600,
          "scopes": ["MANAGE_PAYMENT", "CREATE_VIRTUALCARD", "EDIT_VIRTUALCARD", "REVEAL_VIRTUALCARD", "PCI_COMPLIANCE"]
        }
      }
    }

Almacena el accessToken devuelto y envíalo como Authorization: Bearer <accessToken> en cada solicitud a continuación. Los tokens son de corta duración (expiresIn está en segundos): acuñalos del lado del servidor y renuévalos antes de que expiren. Detalles completos: Credenciales de API.

Los scopes 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 después.

Nunca expongas el clientSecret en un navegador o cliente móvil. Acuña 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 — de forma predeterminada 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, a través del sitio web de Fluz en sandbox.
Programáticamente, mediante la mutación depositCashBalance.

Depositar vía API (depositCashBalance)

Recupera un ID de fuente de fondos con getWallet, luego deposita:

      mutation depositCashBalance($input: DepositCashBalanceInput!) {
        depositCashBalance(input: $input) {
          balances {
            cashBalance { availableBalance totalBalance pendingBalance }
          }
        }
      }

      {
        "input": {
          "idempotencyKey": "0284be6f-1a69-44f7-9da0-5b5edaf45d19",
          "amount": 200.00,
          "depositType": "CASH_BALANCE",
          "bankCardId": "<YOUR_TEST_BANK_CARD_ID>"
        }
      }

El Quickstart de tarjeta de regalo recorre este paso con todo detalle, 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 — no se necesita saldo prefondeado.

Explora programas de tarjeta y elige una oferta

Cada tarjeta virtual se emite contra un programa de tarjeta (una “oferta”): el programa determina la red, el banco emisor, la tasa de recompensas y los límites de gasto dentro de los cuales debe permanecer tu tarjeta. Recupera los programas disponibles para tu cuenta con getVirtualCardOffers.

    query GetVirtualCardOffers {
      getVirtualCardOffers {
        offerId
        programName
        bin
        bankName
        rewardValue
        programLimits {
          dailyLimit
          weeklyLimit
          monthlyLimit
        }
      }
    }

    {
      "data": {
        "getVirtualCardOffers": [
          {
            "offerId": "ed669305-5e43-40a0-9a25-7a15ed174628",
            "programName": "Virtual Card",
            "bin": "543210",
            "bankName": "Bank of Examples",
            "rewardValue": "1.5%",
            "programLimits": {
              "dailyLimit": "500.00",
              "weeklyLimit": "2000.00",
              "monthlyLimit": "5000.00"
            }
          }
        ]
      }
    }

Las ofertas están ordenadas 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 tarjeta virtual.En el sandbox, estos programas de prueba siempre están disponibles:

Offer ID	Program Name	Reward Value
`ed669305-5e43-40a0-9a25-7a15ed174628`	Virtual Card	1.5%
`b23630f6-8d91-43df-84aa-a541e7691197`	Virtual Card - Mastercard Prepaid	1.5%
`592c394e-26cc-44ac-a145-a5f81301fe77`	Brand Locked Virtual Card - Mastercard Prepaid	1.5%

Guarda el offerId que quieras 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 hecha a la medida: elige el patrón que coincida con lo que estás construyendo:

Compra única
Suscripción con tope mensual
Tarjeta presupuestada y acotada en el tiempo

Una tarjeta para exactamente una transacción. Establece spendLimit al monto de la compra y lockCardNextUse: true para que la tarjeta se bloquee sola después de su primera autorización — nada más podrá serle cobrado.

Variables

        {
          "input": {
            "idempotencyKey": "07df5653-43a8-4532-9881-3ab5857bbe12",
            "offerId": "ed669305-5e43-40a0-9a25-7a15ed174628",
            "spendLimit": 150.00,
            "lockCardNextUse": true,
            "cardNickname": "Vendor payment — Acme invoice #1042"
          }
        }

Una tarjeta dedicada a un cargo recurrente. spendLimitDuration: MONTHLY reinicia el límite cada mes, de modo que un aumento de precio o un cargo duplicado más allá del tope se decline automáticamente.

Variables

        {
          "input": {
            "idempotencyKey": "07df5653-43a8-4532-9881-3ab5857bbe13",
            "offerId": "ed669305-5e43-40a0-9a25-7a15ed174628",
            "spendLimit": 29.99,
            "spendLimitDuration": "MONTHLY",
            "cardNickname": "SaaS — analytics subscription"
          }
        }

Una tarjeta para un proyecto o viaje con una fecha de finalización fija. lockDate congela la tarjeta ese día (el valor predeterminado es 47 meses después), y deshabilitar usePrepaymentBalance / useRewardsBalance hace que consuma solo de la cuenta de gasto especificada — fondeo predecible de una sola fuente para una conciliación limpia.

Variables

        {
          "input": {
            "idempotencyKey": "07df5653-43a8-4532-9881-3ab5857bbe14",
            "offerId": "ed669305-5e43-40a0-9a25-7a15ed174628",
            "spendLimit": 2000.00,
            "lockDate": "2026-09-30",
            "userCashBalanceId": "<SPEND_ACCOUNT_ID>",
            "usePrepaymentBalance": false,
            "useRewardsBalance": false,
            "cardNickname": "Q3 conference travel"
          }
        }

Las tres ejecutan la misma mutación:

    mutation createVirtualCard($input: CreateVirtualCardInput!) {
      createVirtualCard(input: $input) {
        virtualCardId
        cardholderName
        virtualCardLast4
        expiryMonth
        expiryYear
        status
        cardType
        initialAmount
        usedAmount
        createdAt
      }
    }

    {
      "data": {
        "createVirtualCard": {
          "virtualCardId": "07df5653-43a8-4532-9881-3ab5857bbe11",
          "cardholderName": "xyz789",
          "virtualCardLast4": "7890",
          "expiryMonth": "12",
          "expiryYear": "27",
          "status": "ACTIVE",
          "cardType": "MULTI_USE",
          "initialAmount": 150.00,
          "usedAmount": 0,
          "createdAt": "2026-07-09T10:00:00Z"
        }
      }
    }

La configuración, de un vistazo

spendLimit

Float

requerido

El máximo que se puede cobrar a la tarjeta — solo se te cobra lo que realmente se use. Debe ajustarse al límite del programa para la duración elegida.

spendLimitDuration

VirtualCardSpendLimitDuration

predeterminado:"LIFETIME"

Cómo se restablece el límite. LIFETIME limita el gasto total; DAILY / WEEKLY / MONTHLY lo convierten en un presupuesto periódico — la opción adecuada para suscripciones y asignaciones de equipo.

lockCardNextUse

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 únicos a proveedores.

lockDate

String

predeterminado:"47 months from creation"

Fecha yyyy-mm-dd en la que la tarjeta se congela. Acota tarjetas a un proyecto, viaje o período de contrato.

primaryFundingSource

VirtualCardFundingSource

predeterminado:"FLUZ_BALANCE"

De dónde se toma el gasto. FLUZ_BALANCE usa tu saldo prefondeado; BANK_ACCOUNT debita de una cuenta vinculada (requiere bankAccountId).

usePrepaymentBalance / useRewardsBalance

Boolean

predeterminado:"true"

De forma predeterminada, una tarjeta también puede tomar de saldos prepago (tarjeta de regalo) y de recompensas. Establece ambos en false para tarjetas solo en efectivo que consumen únicamente del userCashBalanceId especificado — lo más limpio para contabilidad.

memo / transactionCategory

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 EE. UU. 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 tarjeta virtual.

Revela los detalles de la tarjeta

La respuesta de creación omite deliberadamente los números sensibles. Recupera el PAN completo, CVV y vencimiento con revealVirtualCardByVirtualCardId — esto es lo que tú (o tu usuario) introduces en un checkout o agregas a una billetera móvil.

    mutation RevealVirtualCard($virtualCardId: UUID!) {
      revealVirtualCardByVirtualCardId(virtualCardId: $virtualCardId) {
        cardNumber
        expiryMMYY
        cvv
        cardHolderName
        billingAddress {
          streetAddress
          postalCode
          city
          state
        }
      }
    }

    {
      "virtualCardId": "07df5653-43a8-4532-9881-3ab5857bbe11"
    }

Requiere el scope 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 — transmítelos solo sobre TLS, nunca los registres, y muéstralos solo al usuario autorizado.

La mayoría de los checkouts en línea no requieren PIN — pero si tu caso de uso lo necesita (o quieres tap-to-pay), consulta Configurar PIN de tarjeta virtual y Aprovisionamiento por push a billetera digital para agregar la tarjeta a Apple Pay o Google Pay en un toque.

Gasta y luego observa la actividad

Usa los detalles 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 potencia tableros de gasto, conciliación y monitoreo de declinaciones.

    query GetVirtualCardTransactions {
      getVirtualCardTransactions(
        input: {
          virtualCardIds: ["07df5653-43a8-4532-9881-3ab5857bbe11"]
          filters: { transactionTypes: [PURCHASE, REFUND, DECLINE] }
          paginate: { limit: 20, offset: 0 }
        }
      ) {
        virtualCardId
        transactions {
          transactionDate
          transactionType
          transactionStatus
          transactionAmount
          merchantName
          mcc
        }
      }
    }

    {
      "data": {
        "getVirtualCardTransactions": [
          {
            "virtualCardId": "07df5653-43a8-4532-9881-3ab5857bbe11",
            "transactions": [
              {
                "transactionDate": "2026-07-09T14:22:31Z",
                "transactionType": "PURCHASE",
                "transactionStatus": "CLEARED",
                "transactionAmount": 42.17,
                "merchantName": "ACME OFFICE SUPPLY",
                "mcc": 5943
              }
            ]
          }
        ]
      }
    }

Requiere los scopes PCI_COMPLIANCE y REVEAL_VIRTUALCARD. Omite virtualCardIds para obtener 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 tarjeta virtual.

¿Terminaste con la tarjeta? Bloquéala (lockVirtualCard)

Las tarjetas con lockCardNextUse o una lockDate se manejan solas. Para bloquear cualquier otra tarjeta bajo demanda:

      mutation {
        lockVirtualCard(input: { virtualCardId: "07df5653-43a8-4532-9881-3ab5857bbe11" }) {
          virtualCardId
          locked
        }
      }

Requiere el scope EDIT_VIRTUALCARD. El bloqueo es reversible — consulta Desbloquear tarjeta virtual.

Listo 🎉

Has emitido una tarjeta virtual creada para un trabajo específico: elegiste un programa, configuraste controles de gasto, revelaste la tarjeta y seguiste su actividad. Desde aquí, profundiza más:

Editar, bloquear y administrar tarjetas

Cambia límites, apodos y fechas de bloqueo en tarjetas existentes.

Billeteras digitales y PINs

Envía tarjetas a Apple Pay / Google Wallet y configura PINs.

Emisión masiva

Crea hasta 10,000 tarjetas en una sola orden.

Envía 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 demostración.

Comienza

Panel de Fluz

Guías rápidas

Tu primera compra con tarjeta virtual

Antes de comenzar

El flujo completo

La configuración, de un vistazo

Listo 🎉

Editar, bloquear y administrar tarjetas

Billeteras digitales y PINs

Emisión masiva

Envía tarjetas a otros

​Antes de comenzar

​El flujo completo

​La configuración, de un vistazo

​Listo 🎉

Editar, bloquear y administrar tarjetas

Billeteras digitales y PINs

Emisión masiva

Envía tarjetas a otros

Antes de comenzar

El flujo completo

La configuración, de un vistazo

Listo 🎉