> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluz.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

**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`](/features/get-card-offers) 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:

```mermaid theme={null}
stateDiagram-v2
    [*] --> ACTIVE: createVirtualCard
    ACTIVE --> LOCKED: lockVirtualCard
    LOCKED --> ACTIVE: unlockVirtualCard
    ACTIVE --> CLOSED_EXPIRED: lockDate reached, or manually cancelled
    CLOSED_EXPIRED --> [*]
```

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](/features/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:

```bash theme={null}
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](/get-started/refresh-expired-access-token) when you receive a `401`.

## How Funding Works

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

1. The designated **spend account** (`userCashBalanceId`)
2. **Prepaid (gift card) balance** — unless `usePrepaymentBalance: false`
3. **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](/features/create-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](/features/get-card-offers)                     |
| Pre-save a billing address        | Mutation | `CREATE_VIRTUALCARD`                    | [Add Virtual Card Address](/features/add-billing-address)                |
| Issue a card                      | Mutation | `CREATE_VIRTUALCARD`                    | [Create Virtual Card](/features/create-card)                             |
| Retrieve PAN, CVV, expiry         | Mutation | `REVEAL_VIRTUALCARD`                    | [Reveal Virtual Card](/recipes/reveal-virtual-card)                      |
| Update limit, nickname, lock date | Mutation | `EDIT_VIRTUALCARD`                      | [Edit Virtual Card](/features/edit-virtual-card)                         |
| Temporarily block spend           | Mutation | `EDIT_VIRTUALCARD`                      | [Lock Virtual Card](/features/lock-virtual-card)                         |
| Re-enable a locked card           | Mutation | `EDIT_VIRTUALCARD`                      | [Unlock Virtual Card](/features/unlock-virtual-card)                     |
| Check remaining balance (batch)   | Query    | `REVEAL_VIRTUALCARD` + `PCI_COMPLIANCE` | [Get Virtual Card Balance](/recipes/get-virtual-card-balance)            |
| View transaction history          | Query    | `CREATE_VIRTUALCARD`                    | [Get Virtual Card Transactions](/features/get-virtual-card-transactions) |
| Issue cards in bulk (async)       | Mutation | `CREATE_VIRTUALCARD`                    | [Bulk Operations](/features/create-bulk-order)                           |
| Distribute cards via hosted link  | Mutation | `CREATE_SHARE_LINK`                     | [Send Hosted Links With Virtual Cards](/features/send-cards)             |
| Set a PIN                         | Mutation | `EDIT_VIRTUALCARD`                      | [Set Virtual Card PIN](/set-virtual-card-pin)                            |
| Push to Apple Pay / Google Pay    | Mutation | —                                       | [Digital Wallet Push Provisioning](/digital-wallet-push-provisioning)    |
| Apply merchant-specific offers    | —        | —                                       | [Card Linked Offers](/features/card-linked-offers)                       |
| Error reference                   | —        | —                                       | [Virtual Card Error Codes](/features/virtual-card-error-codes)           |

## Next steps

<Card title="Create your first virtual card" icon="credit-card" horizontal href="/features/create-card">
  The full `createVirtualCard` contract — inputs, funding options, spend controls, and examples.
</Card>