Your First Gift Card Purchase

This Quickstart takes you from a fresh Fluz account to a completed staging purchase. You’ll register an app, mint a scoped access token, then deposit funds, browse the merchant catalog, purchase a gift card, and reveal its redemption details — all in the sandbox, where no real money moves.

Prerequisites

A Fluz account — you’ll create staging API credentials and mint an access token in Steps 1–2 below.
Requests go to the sandbox GraphQL endpoint. Nothing here charges a real card — see Staging vs. Live Environment.
Every mutation needs a unique idempotencyKey (a client-generated UUID) so a request is only ever processed once — see Idempotency.

Before you begin

Every call is a POST request to a single GraphQL endpoint. Minting your token (Step 2) authenticates with your API Key; every other call authenticates with your 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 getWallet { getWallet { bankCards { bankCardId lastFourDigits } } }"
  }'

Your sandbox account ships with a pre-added test bank card, so you can run this entire flow immediately. Add more test cards or bank accounts from the Sandbox Accounts page using values from the Test Bank Cards list.

The full flow

Five calls, each one setting up the next. The token carries the scopes; the balance funds the purchase; the merchant slug picks the offer; the purchase returns the gift card ID you reveal.

Create a Fluz account at fluz.app, then open the Developer Console and create a new Staging application. When the credentials appear, copy your API Key, User ID, and Account ID.Full walkthrough: Prepare your accounts.

Exchange credentials for an access token

Mint a short-lived, scoped user access token with your API Key. This call goes to the same GraphQL endpoint, authorized with Authorization: Basic <YOUR_API_KEY>; every later call uses the returned token as a Bearer credential.

curl -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
  -H "Authorization: Basic <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation ($userId: UUID!, $accountId: UUID!, $scopes: [ScopeType!]!) { generateUserAccessToken(userId: $userId, accountId: $accountId, scopes: $scopes) { token scopes } }",
    "variables": {
      "userId": "<YOUR_USER_ID>",
      "accountId": "<YOUR_ACCOUNT_ID>",
      "scopes": ["LIST_OFFERS", "LIST_PAYMENT", "MANAGE_PAYMENT", "MAKE_DEPOSIT", "PURCHASE_GIFTCARD", "REVEAL_GIFTCARD"]
    }
  }'

{
  "data": {
    "generateUserAccessToken": {
      "token": "eyJhbGciOi...",
      "scopes": ["LIST_OFFERS", "LIST_PAYMENT", "MANAGE_PAYMENT", "MAKE_DEPOSIT", "PURCHASE_GIFTCARD", "REVEAL_GIFTCARD"]
    }
  }
}

Store the returned token and send it as Authorization: Bearer <token> on every request below. Tokens are short-lived — mint them server-side and mint a new one with the same mutation when one expires (see Refresh an expired access token). Full details: API credentials.

Scopes gate what the token can do — include only what your flow needs: MANAGE_PAYMENT to add funding sources and deposit, LIST_OFFERS to browse the catalog, and PURCHASE_GIFTCARD / REVEAL_GIFTCARD to buy and reveal.

Never expose your API Key in a browser or mobile client. Mint tokens server-side and forward only the token.

Deposit funds to your Fluz balance

Pre-loading a Fluz balance generally makes gift card purchases faster and can bypass certain velocity checks. You can deposit two ways:

Manually, via the sandbox Fluz website.
Programmatically, via the depositCashBalance mutation (shown below).

First, retrieve a payment method ID (getWallet)

To deposit via API you need the ID of a funding source (e.g. a bankCardId). Run getWallet and save the ID you want to use.

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 } } }"
  }'

Grab the bankCardId or bankAccountId from the response. Managing funding sources via the API requires the MANAGE_PAYMENT scope. More detail: View Funding Sources.

Make the deposit

Use the depositCashBalance mutation. It takes a DepositCashBalanceInput object.

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": "88d2aea1-9461-419e-9ac7-87693b6eea1e"
  }
}

Input fields

string

required

A unique client-generated UUID that guarantees the deposit is processed only once.

Float

required

The amount to deposit.

CashBalanceDepositType

Destination balance. One of CASH_BALANCE, GIFT_CARD_BALANCE, or RESERVE_BALANCE.

UUID

Where the money comes from — provide one of bankAccountId, bankCardId, or paypalVaultId.

Int

Only for GIFT_CARD_BALANCE. A four-digit MCC classifying the business. Use getMccList to retrieve valid values.

UUID

When CASH_BALANCE is selected, the specific spend account to deposit into.

Sample response

{
  "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"
        }
      }
    }
  }
}

Deposits may settle instantly or within 2–5 business days depending on the funding source and settlement type. The balances object in the response reflects your current available balance. See Check Account Balance to re-query it at any time.

Browse merchants and pick an offer

With a balance ready, fetch the catalog of available merchants and their cashback offers using 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 }
}

The catalog is sorted by cashback percentage by default, so the highest offers appear first.

Useful arguments

String

Filter merchants by name.

OffsetInput

{ limit, offset }. Default and max limit is 20.

OfferTypesInput

Boolean flags for which offer types to return, e.g. { giftCardOffer: true, cardLinkedOffer: false }.

FilterByInput

Filter offers within each merchant, e.g. by deliveryFormat (URL, CODES, PIN_AS_CODE, PIN_WITH_URL).

Pagination: the response may return fewer results than your limit. To pull the full catalog, keep incrementing offset by your limit and stop when the API returns an empty array ([]). The unfiltered catalog is large — fetch it at most once per day, and use name or offerTypes for targeted lookups.

Optional: get the single best offer for a merchant (getOfferQuote)

If you already know the merchant and amount, getOfferQuote returns the top available offer directly — including live stock info.

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": {
    "merchantSlug": "burger-king",
    "denomination": 50.00,
    "paymentMethod": "FLUZPAY"
  }
}

merchantSlug and denomination are required. paymentMethod defaults to FLUZPAY (your Fluz balance) and also accepts BANK_CARD, BANK_ACCOUNT, PAYPAL, APPLE_PAY, and GOOGLE_PAY.

Cashback rates change regularly. Always confirm the current rate before purchasing.

Purchase a gift card

Use the purchaseGiftCard mutation. You can identify what to buy in two ways:

Option A — Merchant slug (recommended)
Option B — Specific offer ID

Pass a merchantSlug and Fluz automatically applies the best available offer for that merchant.

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

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

Pass an offerId you selected from the catalog to purchase that exact offer.

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
  }
}

Input fields

string

required

A unique client-generated UUID so the purchase is processed only once.

UUID / String

required

Provide one. merchantSlug auto-selects the best rate; offerId targets a specific offer.

Float

required

The gift card amount to purchase.

UUID / Float

How to pay. Use balanceAmount (Fluz balance), bankAccountId, bankCardId, or paypalVaultId. You may combine your Fluz balance with another source.

Boolean

default:"true"

Falls back to your Fluz balance if another payment method fails. Set to false to disable that fallback.

Float

Minimum reward rate to accept when purchasing via merchantSlug.

UUID

Forces a specific exclusive rate. Found in getMerchants for offers of type EXCLUSIVE_RATE_OFFER.

UUID

The spend account (cash balance) to charge.

String / String / UUID

Optional expense metadata. memo max 255 chars; categories are created on first use. See Add Expense Details.

Sample response

{
  "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..."
      }
    }
  }
}

Hold on to the giftCardId from the response — you’ll use it to reveal the card in the next step. If a purchase fails, check Gift Card Error Codes.

Reveal the gift card details

Finally, retrieve the redeemable details (code, PIN, and/or URL).

Don't have the giftCardId? List your cards first (getGiftCards)

Skip this if you just captured a giftCardId in Step 3. Otherwise, list your gift cards:

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

You can filter with status and userCashBalanceId, and page with paginate.

Reveal redemption details

Call revealGiftCardByGiftCardId with the giftCardId.

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

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

Sample response

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

Redemption fields vary by merchant. Some cards return an alphanumeric code with no pin; others return only a url. Always render based on the deliveryFormat returned by getGiftCards (not getMerchants) — a merchant’s active offer can change after purchase, and getGiftCards reflects the format the card was actually bought under.

Details not returned immediately? Poll revealGiftCardByGiftCardId with exponential backoff: start at 300ms, then double (300 → 600 → 1200 → 2400ms…) up to a max delay of 180000ms (3 minutes). Stop as soon as details come back. This balances responsiveness with load and avoids unnecessary timeouts.

You’re done 🎉

You’ve run a complete transaction — funded a balance, browsed offers, purchased a gift card, and revealed it. From here, explore the rest of the API:

Virtual Cards

Issue and manage network-accepted virtual cards.

Wallets & Transfers

Open spend accounts and move funds between them.

Transaction Activity

Pull, filter, and annotate transaction history.

Embedded Widgets

Drop Fluz flows straight into your own UI.

Want to learn more? Contact us at support@fluz.app to speak with our experts or request a demo.

Get started

Fluz Dashboard

Quickstarts

Your First Gift Card Purchase

Before you begin

The full flow

Make the deposit

Input fields

Useful arguments

Input fields

Reveal redemption details

You’re done 🎉

Virtual Cards

Wallets & Transfers

Transaction Activity

Embedded Widgets

​Before you begin

​The full flow

​Make the deposit

​Input fields

​Useful arguments

​Input fields

​Reveal redemption details

​You’re done 🎉

Virtual Cards

Wallets & Transfers

Transaction Activity

Embedded Widgets

Before you begin

The full flow

Make the deposit

Input fields

Useful arguments

Input fields

Reveal redemption details

You’re done 🎉