Tu primera compra de tarjeta de regalo

Este Quickstart te lleva desde una cuenta nueva de Fluz hasta una compra completada en staging. Registrarás una app, emitirás un token de acceso con alcance específico, luego depositarás fondos, explorarás el catálogo de comercios, comprarás una tarjeta de regalo y revelarás sus detalles de canje, todo en el sandbox, donde no se mueve dinero real.

Requisitos previos

Una cuenta de Fluz: crearás credenciales de API de staging y emitirás un token de acceso en los Pasos 1–2 a continuación.
Las solicitudes van al endpoint GraphQL del sandbox. Nada aquí carga 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 emitir tu token (Paso 2), cada llamada es una solicitud POST a un único endpoint GraphQL, autenticada con tu token bearer:

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 getWallet { getWallet { bankCards { bankCardId lastFourDigits } } }"
  }'

Tu cuenta de sandbox incluye una tarjeta bancaria de prueba preagregada, para que puedas ejecutar todo este flujo de inmediato. Agrega más tarjetas de prueba o cuentas bancarias desde la página de Sandbox Accounts usando valores de la lista Test Bank Cards.

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 secreto solo se muestra una vez.Guía completa: Prepara tus cuentas.

Intercambia credenciales por un token de acceso

Emite un token de acceso de usuario de corta duración y con alcance específico a partir de las credenciales de tu app. Esta llamada va al servicio OAuth; todas las llamadas posteriores usan 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": ["LIST_OFFERS", "LIST_PAYMENT", "MANAGE_PAYMENT", "PURCHASE_GIFTCARD", "REVEAL_GIFTCARD"]
    }
  }'

{
  "data": {
    "generateUserAccessToken": {
      "accessToken": "eyJhbGciOi...",
      "expiresIn": 3600,
      "scopes": ["LIST_OFFERS", "LIST_PAYMENT", "MANAGE_PAYMENT", "PURCHASE_GIFTCARD", "REVEAL_GIFTCARD"]
    }
  }
}

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): emítelos del lado del servidor y renuévalos antes del vencimiento. Detalles completos: Credenciales de API.

Los scopes controlan lo que el token puede hacer: incluye solo lo que tu flujo necesita: MANAGE_PAYMENT para agregar fuentes de fondos y depositar, LIST_OFFERS para explorar el catálogo, y PURCHASE_GIFTCARD / REVEAL_GIFTCARD para comprar y revelar.

Nunca expongas el clientSecret en un navegador o cliente móvil. Emite tokens del lado del servidor y reenvía solo el token.

Deposita fondos a tu saldo de Fluz

Precargar un saldo de Fluz generalmente hace que las compras de tarjetas de regalo sean más rápidas y puede evitar ciertos controles de velocidad. Puedes depositar de dos maneras:

Manualmente, a través del sitio web de Fluz en sandbox.
Programáticamente, a través de la mutación depositCashBalance (se muestra a continuación).

Primero, recupera un ID de método de pago (getWallet)

Para depositar vía API necesitas el ID de una fuente de fondos (por ejemplo, un bankCardId). Ejecuta getWallet y guarda el ID que quieres usar.

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 getWallet { getWallet { bankCards { bankCardId lastFourDigits } bankAccounts { bankAccountId } } }"
  }'

Toma el bankCardId o bankAccountId de la respuesta. Administrar fuentes de fondos vía API requiere el scope MANAGE_PAYMENT. Más detalle: Ver fuentes de fondos.

Realiza el depósito

Usa la mutación depositCashBalance. Acepta un objeto DepositCashBalanceInput.

mutation depositCashBalance($input: DepositCashBalanceInput!) {
  depositCashBalance(input: $input) {
    cashBalanceDeposits {
      cashBalanceDepositId
      depositDisplayId
      depositAmount
      status
      cashBalanceDepositType
    }
    balances {
      cashBalance { availableBalance totalBalance pendingBalance }
      giftCardCashBalance { availableBalance totalBalance pendingBalance }
    }
  }
}

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

Campos de entrada

idempotencyKey

string

requerido

Un UUID único generado por el cliente que garantiza que el depósito se procese solo una vez.

amount

Float

requerido

El monto a depositar.

depositType

CashBalanceDepositType

Saldo de destino. Uno de CASH_BALANCE, GIFT_CARD_BALANCE o RESERVE_BALANCE.

Funding source

UUID

De dónde proviene el dinero: proporciona uno de bankAccountId, bankCardId o paypalVaultId.

merchantCategoryCode

Int

Solo para GIFT_CARD_BALANCE. Un MCC de cuatro dígitos que clasifica el negocio. Usa getMccList para recuperar valores válidos.

userCashBalanceId

UUID

Cuando se selecciona CASH_BALANCE, la cuenta de gasto específica en la que depositar.

Respuesta de ejemplo

{
  "data": {
    "depositCashBalance": {
      "cashBalanceDeposits": [
        {
          "cashBalanceDepositId": "5f5c5b5f-4c4b-4e4e-9e9e-4f4f4f4f4f4f",
          "depositDisplayId": "102370",
          "depositAmount": "100.00",
          "status": "COMPLETED",
          "cashBalanceDepositType": "CASH_BALANCE"
        }
      ],
      "balances": {
        "cashBalance": {
          "availableBalance": "100.00",
          "totalBalance": "100.00",
          "pendingBalance": "0.00"
        },
        "giftCardCashBalance": {
          "availableBalance": "0.00",
          "totalBalance": "0.00",
          "pendingBalance": "0.00"
        }
      }
    }
  }
}

Los depósitos pueden liquidarse al instante o dentro de 2–5 días hábiles según la fuente de fondos y el tipo de liquidación. El objeto balances en la respuesta refleja tu saldo disponible actual. Consulta Verificar saldo de cuenta para volver a consultarlo en cualquier momento.

Explora comercios y elige una oferta

Con un saldo listo, obtén el catálogo de comercios disponibles y sus ofertas de cashback usando getMerchants.

query GetMerchantCatalog(
  $paginate: OffsetInput
  $offerTypes: OfferTypesInput
  $filterBy: FilterByInput
) {
  getMerchants(paginate: $paginate, offerTypes: $offerTypes, filterBy: $filterBy) {
    merchantId
    name
    slug
    logoUrl
    faceplateUrl
    offers {
      offeringMerchantId
      offerId
      type
      deliveryFormat
      barcodeType
      offerRates {
        maxUserRewardValue
        cashbackVoucherRewardValue
        boostRewardValue
        denominations
        allowedPaymentMethods
      }
    }
  }
}

{
  "paginate": { "limit": 20, "offset": 0 },
  "offerTypes": { "giftCardOffer": true, "cardLinkedOffer": false }
}

El catálogo se ordena por porcentaje de cashback de forma predeterminada, por lo que las ofertas más altas aparecen primero.

Argumentos útiles

name

String

Filtra comercios por nombre.

paginate

OffsetInput

{ limit, offset }. El limit predeterminado y máximo es 20.

offerTypes

OfferTypesInput

Indicadores booleanos para qué tipos de ofertas devolver, por ejemplo { giftCardOffer: true, cardLinkedOffer: false }.

filterBy

FilterByInput

Filtra ofertas dentro de cada comercio, por ejemplo por deliveryFormat (URL, CODES, PIN_AS_CODE, PIN_WITH_URL).

Paginación: la respuesta puede devolver menos resultados que tu limit. Para extraer el catálogo completo, sigue incrementando offset por tu limit y detente cuando la API devuelva un arreglo vacío ([]). El catálogo sin filtrar es grande: recupéralo como máximo una vez al día y usa name u offerTypes para búsquedas específicas.

Opcional: obtén la mejor oferta única para un comercio (getOfferQuote)

Si ya conoces el comercio y el monto, getOfferQuote devuelve directamente la mejor oferta disponible, incluyendo información de inventario en vivo.

query getOfferQuote($input: GetOfferQuoteInput!) {
  getOfferQuote(input: $input) {
    offeringMerchantId
    offerId
    type
    hasStockInfo
    denominationsType
    termsAndConditions
    offerRates {
      maxUserRewardValue
      denominations
      allowedPaymentMethods
    }
    stockInfo {
      ... on StockInfoVariableType {
        __typename
        description
        maxDenomination
        minDenomination
      }
      ... on StockInfoFixedType {
        __typename
        denomination
        availableStock
      }
    }
  }
}

{
  "input": {
    "slug": "starbucks",
    "denomination": 50.00,
    "paymentMethod": "FLUZPAY"
  }
}

slug y denomination son obligatorios. paymentMethod predetermina a FLUZPAY (tu saldo de Fluz) y también acepta BANK_CARD, BANK_ACCOUNT, PAYPAL, APPLE_PAY y GOOGLE_PAY.

Las tasas de cashback cambian con regularidad. Confirma siempre la tasa actual antes de comprar.

Compra una tarjeta de regalo

Usa la mutación purchaseGiftCard. Puedes identificar qué comprar de dos maneras:

Opción A — Slug del comercio (recomendado)
Opción B — ID de oferta específico

Pasa un merchantSlug y Fluz aplicará automáticamente la mejor oferta disponible para ese comercio.

mutation purchaseGiftCard($input: PurchaseGiftCardInput!) {
  purchaseGiftCard(input: $input) {
    purchaseDisplayId
    purchaseAmount
    giftCard {
      giftCardId
      status
      termsAndConditions
    }
  }
}

{
  "input": {
    "idempotencyKey": "0284be6f-1a69-44f7-9da0-5b5edaf45d19",
    "merchantSlug": "starbucks",
    "amount": 50.00,
    "balanceAmount": 50.00
  }
}

Pasa un offerId que seleccionaste del catálogo para comprar esa oferta exacta.

mutation purchaseGiftCard($input: PurchaseGiftCardInput!) {
  purchaseGiftCard(input: $input) {
    purchaseDisplayId
    purchaseAmount
    giftCard {
      giftCardId
      status
      termsAndConditions
    }
  }
}

{
  "input": {
    "idempotencyKey": "0284be6f-1a69-44f7-9da0-5b5edaf45d19",
    "offerId": "0284be6f-1a69-44f7-9da0-5b5edaf45d19",
    "amount": 50.00,
    "balanceAmount": 50.00
  }
}

Campos de entrada

idempotencyKey

string

requerido

Un UUID único generado por el cliente para que la compra se procese solo una vez.

offerId / merchantSlug

UUID / String

requerido

Proporciona uno. merchantSlug selecciona automáticamente la mejor tasa; offerId apunta a una oferta específica.

amount

Float

requerido

El monto de la tarjeta de regalo a comprar.

Funding source

UUID / Float

Cómo pagar. Usa balanceAmount (saldo de Fluz), bankAccountId, bankCardId o paypalVaultId. Puedes combinar tu saldo de Fluz con otra fuente.

defaultToBalance

Boolean

predeterminado:"true"

Recurre a tu saldo de Fluz si falla otro método de pago. Establécelo en false para deshabilitar ese fallback.

minRewardRate

Float

Tasa mínima de recompensa a aceptar al comprar vía merchantSlug.

exclusiveRateId

UUID

Fuerza una tasa exclusiva específica. Se encuentra en getMerchants para ofertas de tipo EXCLUSIVE_RATE_OFFER.

userCashBalanceId

UUID

La cuenta de gasto (saldo en efectivo) a cargar.

memo / transactionCategory / attachmentId

String / String / UUID

Metadatos de gasto opcionales. memo máximo 255 caracteres; las categorías se crean en el primer uso. Consulta Agregar detalles de gasto.

Respuesta de ejemplo

{
  "data": {
    "purchaseGiftCard": {
      "purchaseDisplayId": "1019688",
      "purchaseAmount": 50.00,
      "giftCard": {
        "giftCardId": "85de8b3e-4e72-462c-8ed1-a6f4982e22f7",
        "status": "ACTIVE",
        "termsAndConditions": "Except as required by law, Gift Cards cannot be transferred for..."
      }
    }
  }
}

Conserva el giftCardId de la respuesta: lo usarás para revelar la tarjeta en el siguiente paso. Si una compra falla, consulta Códigos de error de tarjetas de regalo.

Revela los detalles de la tarjeta de regalo

Finalmente, recupera los detalles canjeables (código, PIN y/o URL).

¿No tienes el giftCardId? Lista tus tarjetas primero (getGiftCards)

Omite esto si acabas de capturar un giftCardId en el Paso 3. De lo contrario, lista tus tarjetas de regalo:

query GetGiftCards {
  getGiftCards(paginate: { limit: 20, offset: 0 }) {
    giftCardId
    status
    createdAt
    deliveryFormat
    termsAndConditions
    merchant { merchantId name slug }
  }
}

Puedes filtrar con status y userCashBalanceId, y paginar con paginate.

Revela los detalles de canje

Llama a revealGiftCardByGiftCardId con el giftCardId.

mutation RevealGiftCard($giftCardId: UUID!) {
  revealGiftCardByGiftCardId(giftCardId: $giftCardId) {
    code
    pin
    url
    termsAndConditions
  }
}

{
  "giftCardId": "7c57c381-4b19-49e4-bbb0-404a45166ee4"
}

Respuesta de ejemplo

{
  "data": {
    "revealGiftCardByGiftCardId": {
      "code": "9877890000000000",
      "pin": "2014",
      "url": null,
      "termsAndConditions": "Except as required by law, Gift Cards cannot be transferred for..."
    }
  }
}

Los campos de canje varían por comercio. Algunas tarjetas devuelven un code alfanumérico sin pin; otras devuelven solo una url. Siempre representa según el deliveryFormat devuelto por getGiftCards (no getMerchants) — la oferta activa de un comercio puede cambiar después de la compra, y getGiftCards refleja el formato bajo el cual la tarjeta realmente se compró.

¿Los detalles no se devuelven de inmediato? Haz polling a revealGiftCardByGiftCardId con backoff exponencial: empieza en 300ms, luego duplica (300 → 600 → 1200 → 2400ms…) hasta un retraso máximo de 180000ms (3 minutos). Detente tan pronto como regresen los detalles. Esto equilibra la rapidez con la carga y evita timeouts innecesarios.

¡Listo! 🎉

Ejecutaste una transacción completa: financiastes un saldo, exploraste ofertas, compraste una tarjeta de regalo y la revelaste. A partir de aquí, explora el resto del API:

Tarjetas virtuales

Emite y gestiona tarjetas virtuales aceptadas por la red.

Billeteras y transferencias

Abre cuentas de gasto y mueve fondos entre ellas.

Actividad de transacciones

Extrae, filtra y anota el historial de transacciones.

Widgets embebidos

Integra flujos de Fluz directamente en tu propia UI.

¿Quieres saber más? Contáctanos en support@fluz.app para hablar con nuestros expertos o solicitar una demo.

Comienza

Panel de Fluz

Guías rápidas

Tu primera compra de tarjeta de regalo

Antes de comenzar

El flujo completo

Realiza el depósito

Campos de entrada

Argumentos útiles

Campos de entrada

Revela los detalles de canje

¡Listo! 🎉

Tarjetas virtuales

Billeteras y transferencias

Actividad de transacciones

Widgets embebidos

​Antes de comenzar

​El flujo completo

​Realiza el depósito

​Campos de entrada

​Argumentos útiles

​Campos de entrada

​Revela los detalles de canje

​¡Listo! 🎉

Tarjetas virtuales

Billeteras y transferencias

Actividad de transacciones

Widgets embebidos

Antes de comenzar

El flujo completo

Realiza el depósito

Campos de entrada

Argumentos útiles

Campos de entrada

Revela los detalles de canje

¡Listo! 🎉