Your First Virtual Card Purchase

This Quickstart takes you from a fresh Fluz account to an issued, spendable virtual card. You’ll register an app, mint a scoped access token, then browse card programs, create a card configured for your use case, reveal its details, and watch its transactions — 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

Except for minting your token (Step 2), every call is a POST request to a single GraphQL endpoint, authenticated 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 GetVirtualCardOffers { getVirtualCardOffers { offerId programName rewardValue } }"
  }'

Staging ships with test card programs ready to issue against, and your sandbox account includes a pre-added test bank card for funding. See Test Merchants and Test Bank Cards for the full sandbox data set.

The full flow

Create a Fluz account at fluz.app, then open the Developer Console and create a new Staging application. When the credentials appear, copy your clientId and clientSecret — the secret is shown only once.Full walkthrough: Prepare your accounts.

Exchange credentials for an access token

Mint a short-lived, scoped user access token from your app credentials. This call goes to the OAuth service; every later call uses the returned token as a Bearer credential.

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

Store the returned accessToken and send it as Authorization: Bearer <accessToken> on every request below. Tokens are short-lived (expiresIn is in seconds) — mint them server-side and refresh before expiry. Full details: API credentials.

Scopes gate what the token can do — include only what your flow needs: MANAGE_PAYMENT to fund your balance, CREATE_VIRTUALCARD to browse programs and issue cards, REVEAL_VIRTUALCARD + PCI_COMPLIANCE to reveal cards and pull their transactions, and EDIT_VIRTUALCARD to lock, unlock, or edit cards later.

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

Fund your Fluz balance

Virtual cards are funded from your account when they’re used — by default from your Fluz balance (FLUZ_BALANCE). Make sure there’s enough available balance to cover the spend limit you plan to set. You can fund two ways:

Manually, via the sandbox Fluz website.
Programmatically, via the depositCashBalance mutation.

Deposit via API (depositCashBalance)

Retrieve a funding source ID with getWallet, then deposit:

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

The gift card Quickstart walks through this step in full detail, including retrieving payment method IDs with getWallet.

Prefer to fund cards from a linked bank account instead? Set primaryFundingSource: BANK_ACCOUNT at card creation (Step 5) and pass the bankAccountId — no pre-funded balance needed.

Browse card programs and pick an offer

Every virtual card is issued against a card program (an “offer”): the program determines the network, issuing bank, reward rate, and the spend limits your card must stay within. Fetch the programs available to your account with 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"
            }
          }
        ]
      }
    }

Offers are sorted by rewardValue, so the highest-earning programs appear first. You can filter with the optional input — cardType (DEBIT / PREPAID), cardNetwork (MASTERCARD / VISA), and cardBrandLocked. Full reference: Get Virtual Card Offers.In the sandbox, these test programs are always available:

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%

Save the offerId you want and note its programLimits — the spendLimit you set in the next step must fit within the program’s limit for your chosen duration.

Create the card, configured for your use case

Issue the card with createVirtualCard. The input’s settings are what turn a generic card into a purpose-built one — pick the pattern that matches what you’re building:

One-off purchase
Subscription with a monthly cap
Budgeted, time-boxed card

A card for exactly one transaction. Set spendLimit to the purchase amount and lockCardNextUse: true so the card locks itself after its first authorization — nothing else can ever be charged to it.

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

A card dedicated to one recurring charge. spendLimitDuration: MONTHLY resets the limit each month, so a price hike or duplicate charge beyond the cap is declined automatically.

Variables

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

A card for a project or trip with a hard end date. lockDate freezes the card on that day (default is 47 months out), and disabling usePrepaymentBalance / useRewardsBalance makes it draw only from the specified spend account — predictable, single-source funding for clean reconciliation.

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

All three run the same mutation:

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

The settings, at a glance

spendLimit

Float

required

The maximum the card can be charged — you’re only ever charged for what’s actually used. Must fit within the program’s limit for your chosen duration.

spendLimitDuration

VirtualCardSpendLimitDuration

default:"LIFETIME"

How the limit resets. LIFETIME caps total spend; DAILY / WEEKLY / MONTHLY make it a rolling budget — the right choice for subscriptions and team allowances.

lockCardNextUse

Boolean

default:"false"

Locks the card after its first successful use — the “virtual single-use card” pattern for one-off vendor payments.

lockDate

String

default:"47 months from creation"

yyyy-mm-dd date the card freezes. Time-box cards to a project, trip, or contract period.

primaryFundingSource

VirtualCardFundingSource

default:"FLUZ_BALANCE"

Where spend is drawn from. FLUZ_BALANCE uses your pre-funded balance; BANK_ACCOUNT pulls from a linked account (requires bankAccountId).

usePrepaymentBalance / useRewardsBalance

Boolean

default:"true"

By default a card may also draw from prepaid (gift card) and rewards balances. Set both to false for cash-only cards that draw solely from the specified userCashBalanceId — cleanest for accounting.

memo / transactionCategory

String

Optional expense metadata attached to the resulting transaction — categories are created on first use. See Add Expense Details.

Billing address: if your account doesn’t have one on file, pass a billingAddress (or a saved userAddressId). It must be a real, deliverable US address — no PO boxes — or creation fails with VC-0025. See Address Formatting Requirements.

Hold on to the virtualCardId from the response — you’ll use it to reveal the card next. If creation fails, check Virtual Card Error Codes.

Reveal the card details

The create response deliberately excludes the sensitive numbers. Retrieve the full PAN, CVV, and expiry with revealVirtualCardByVirtualCardId — this is what you (or your user) enter at a checkout or add to a mobile wallet.

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

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

Requires the REVEAL_VIRTUALCARD scope.

The response contains the full card number and CVV in plaintext. Treat it as sensitive cardholder data — transmit over TLS only, never log it, and display it only to the authorized user.

Most online checkouts don’t need a PIN — but if your use case does (or you want tap-to-pay), see Set Virtual Card PIN and Digital Wallet Push Provisioning to add the card to Apple Pay or Google Pay in one tap.

Spend, then watch the activity

Use the revealed details anywhere the card network is accepted, within the limits you set. Then pull the card’s activity with getVirtualCardTransactions to confirm the charge — the same query powers spend dashboards, reconciliation, and decline monitoring.

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

Requires the PCI_COMPLIANCE and REVEAL_VIRTUALCARD scopes. Omit virtualCardIds to pull activity across every card on the account, and filter by date range for statement-style views. Full reference: Get Virtual Card Transactions.

Done with the card? Lock it (lockVirtualCard)

Cards with lockCardNextUse or a lockDate handle themselves. To lock any other card on demand:

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

Requires the EDIT_VIRTUALCARD scope. Locking is reversible — see Unlock Virtual Card.

You’re done 🎉

You’ve issued a virtual card built for a specific job — picked a program, set spend controls, revealed the card, and tracked its activity. From here, go deeper:

Edit, lock & manage cards

Change limits, nicknames, and lock dates on existing cards.

Digital wallets & PINs

Push cards into Apple Pay / Google Wallet and set PINs.

Bulk issuance

Create up to 10,000 cards in a single order.

Send cards to others

Distribute cards to recipients by link, email, or SMS.

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 Virtual Card Purchase

Before you begin

The full flow

The settings, at a glance

You’re done 🎉

Edit, lock & manage cards

Digital wallets & PINs

Bulk issuance

Send cards to others

​Before you begin

​The full flow

​The settings, at a glance

​You’re done 🎉

Edit, lock & manage cards

Digital wallets & PINs

Bulk issuance

Send cards to others

Before you begin

The full flow

The settings, at a glance

You’re done 🎉