Overview - Fluz

Pre-Funded Virtual Cards are network-branded (Visa / Mastercard) cards issued instantly via the Fluz API. They earn cashback at every merchant that accepts the network — and can be layered with gift-card routing at 400+ brands for even higher rewards.

What Is a Fluz Virtual Card?

A Fluz Pre-Funded Virtual Card is a network-branded, instantly issued card that lives entirely in software. Unlike a physical card:

No plastic, no shipping — the card is available the moment createVirtualCard resolves.
Pre-funded — the spend limit is reserved at creation time from a Fluz Wallet, gift-card balance, rewards balance, or a linked bank account.
Scoped — each card has its own spend limit, duration, lock date, and optional single-use flag, so you control exactly how much can be charged and for how long.
Full network acceptance — issued on Mastercard (debit or prepaid) or Visa rails, usable anywhere those networks are accepted online or in-store.

Cards earn a base cashback on all spend via interchange economics. At supported merchants, card-linked offers can layer on additional returns.

Card Types

Type	Description
Standard Virtual Card	Works at all merchants on the card network
Brand-Locked Virtual Card	Restricted to a specific merchant — useful for targeted incentive programs or spend controls

Use getVirtualCardOffers to enumerate all programs available to your account, including network type (Mastercard / Visa), card type (debit / prepaid), issuing bank, and per-program spend limits.

Card Lifecycle

A card moves through the following states: A card set with lockCardNextUse: true transitions automatically from ACTIVE to LOCKED after its first successful authorization — no additional API call required. See Edit Virtual Card for how to modify this setting post-creation.

Required Scopes

All virtual card operations require a User Access Token generated with the appropriate scopes. The three core scopes are:

Scope	Used By
`CREATE_VIRTUALCARD`	Create cards, fetch offers, check balances, get transactions
`REVEAL_VIRTUALCARD`	Reveal PAN, CVV, and expiry; also required for `getVirtualCardBalance` alongside `PCI_COMPLIANCE`
`EDIT_VIRTUALCARD`	Edit, lock, unlock, set PIN

Generate a token with all three scopes before calling any virtual card endpoint:

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

Pass the returned token as Authorization: Bearer <token> on all subsequent calls. See Refresh an Expired User Access Token when you receive a 401.

How Funding Works

When a card is charged, Fluz draws funds in this priority order by default:

The designated spend account (userCashBalanceId)
Prepaid (gift card) balance — unless usePrepaymentBalance: false
Rewards balance — unless useRewardsBalance: false

You can also fund directly from a linked bank account by setting primaryFundingSource: BANK_ACCOUNT. Full input details and examples are on Create Virtual Card.

Spend Limit Durations

The spendLimit you set applies per the chosen spendLimitDuration:

Duration	Behavior
`LIFETIME`	Applies across the card’s entire lifespan (default)
`DAILY`	Resets each calendar day
`WEEKLY`	Resets weekly
`MONTHLY`	Resets on the first of each month

You are only charged for the amount actually spent — the spend limit is an authorization ceiling, not a pre-charge. Unused balance stays in your wallet.

Single-Use Cards

Set lockCardNextUse: true at creation (or update it via editVirtualCard) to lock the card automatically after its first authorization. This is the recommended pattern for:

One-time vendor payments
Single-transaction disbursements
Agentic payment flows where a card should be consumed after one use

All Virtual Card Operations

Operation	Type	Scope(s)	Page
Discover available programs	Query	`CREATE_VIRTUALCARD`	Get Virtual Card Offers
Pre-save a billing address	Mutation	`CREATE_VIRTUALCARD`	Add Virtual Card Address
Issue a card	Mutation	`CREATE_VIRTUALCARD`	Create Virtual Card
Retrieve PAN, CVV, expiry	Mutation	`REVEAL_VIRTUALCARD`	Reveal Virtual Card
Update limit, nickname, lock date	Mutation	`EDIT_VIRTUALCARD`	Edit Virtual Card
Temporarily block spend	Mutation	`EDIT_VIRTUALCARD`	Lock Virtual Card
Re-enable a locked card	Mutation	`EDIT_VIRTUALCARD`	Unlock Virtual Card
Check remaining balance (batch)	Query	`REVEAL_VIRTUALCARD` + `PCI_COMPLIANCE`	Get Virtual Card Balance
View transaction history	Query	`CREATE_VIRTUALCARD`	Get Virtual Card Transactions
Issue cards in bulk (async)	Mutation	`CREATE_VIRTUALCARD`	Bulk Operations
Distribute cards via hosted link	Mutation	`CREATE_SHARE_LINK`	Send Hosted Links With Virtual Cards
Set a PIN	Mutation	`EDIT_VIRTUALCARD`	Set Virtual Card PIN
Push to Apple Pay / Google Pay	Mutation	—	Digital Wallet Push Provisioning
Apply merchant-specific offers	—	—	Card Linked Offers
Error reference	—	—	Virtual Card Error Codes

Next steps

Create your first virtual card

The full createVirtualCard contract — inputs, funding options, spend controls, and examples.

​What Is a Fluz Virtual Card?

​Card Types

​Card Lifecycle

​Required Scopes

​How Funding Works

​Spend Limit Durations

​Single-Use Cards

​All Virtual Card Operations

​Next steps