> ## 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.

# 概览

**预充值虚拟卡** 是通过 Fluz API 即时发行的网络品牌（Visa / Mastercard）卡。它在所有接受该网络的商户处都可获得返现，并且可以在 400+ 个品牌叠加礼品卡路由以获取更高回报。

## 什么是 Fluz 虚拟卡？

Fluz 的 **预充值虚拟卡** 是完全存在于软件中的网络品牌、即时发行的卡。不同于实体卡：

* **无塑料、无邮寄** —— 一旦 `createVirtualCard` 返回，卡片立刻可用。
* **预充值** —— 消费限额在创建时从 Fluz 钱包、礼品卡余额、奖励余额，或关联的银行账户中预留。
* **范围限定** —— 每张卡都有独立的消费限额、有效期、锁定日期以及可选的单次使用标记，你可以精确控制可被扣款的金额与时长。
* **完整的网络受理** —— 通过 Mastercard（借记或预付）或 Visa 网络发行，可在这些网络被线上或线下接受的任何地方使用。

卡片通过交换费经济在所有消费上获得基础**返现**。在支持的商户处，卡片关联优惠可叠加额外回报。

## 卡片类型

| 类型          | 描述                      |
| ----------- | ----------------------- |
| **标准虚拟卡**   | 适用于卡网络上的所有商户            |
| **品牌锁定虚拟卡** | 仅限特定商户使用——适合定向激励计划或消费控制 |

使用 [`getVirtualCardOffers`](/features/get-card-offers) 列举你账户可用的所有计划，包括网络类型（Mastercard / Visa）、卡片类型（借记 / 预付）、发卡银行，以及每个计划的消费限额。

## 卡片生命周期

一张卡会经历以下状态：

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

设置了 `lockCardNextUse: true` 的卡，在首次授权成功后会自动从 `ACTIVE` 转换为 `LOCKED` —— 无需额外的 API 调用。参见 [编辑虚拟卡](/features/edit-virtual-card) 了解如何在创建后修改该设置。

## 必需的范围（Scopes）

所有虚拟卡操作都需要使用带有相应范围的**用户访问令牌**。三个核心范围为：

| 范围                   | 用途                                                                 |
| -------------------- | ------------------------------------------------------------------ |
| `CREATE_VIRTUALCARD` | 创建卡片、获取优惠、检查余额、查询交易                                                |
| `REVEAL_VIRTUALCARD` | 展示卡号（PAN）、CVV 和有效期；与 `PCI_COMPLIANCE` 一起用于 `getVirtualCardBalance` |
| `EDIT_VIRTUALCARD`   | 编辑、锁定、解锁、设置 PIN                                                    |

在调用任何虚拟卡端点前，生成包含这三个范围的令牌：

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

将返回的 `token` 以 `Authorization: Bearer <token>` 添加到所有后续调用。收到 `401` 时参见 [刷新已过期的用户访问令牌](/get-started/refresh-expired-access-token)。

## 资金如何运作

当卡被扣款时，Fluz 默认按以下优先级划拨资金：

1. 指定的**消费账户**（`userCashBalanceId`）
2. **预付（礼品卡）余额** —— 除非设置了 `usePrepaymentBalance: false`
3. **奖励余额** —— 除非设置了 `useRewardsBalance: false`

你也可以通过设置 `primaryFundingSource: BANK_ACCOUNT`，直接从**关联银行账户**扣款。完整的输入细节和示例参见 [创建虚拟卡](/features/create-card)。

## 消费限额周期

你设置的 `spendLimit` 将依据所选的 `spendLimitDuration` 生效：

| 周期         | 行为              |
| ---------- | --------------- |
| `LIFETIME` | 适用于卡片整个生命周期（默认） |
| `DAILY`    | 每个日历日重置         |
| `WEEKLY`   | 每周重置            |
| `MONTHLY`  | 每月第一天重置         |

你**只会为实际消费的金额付费**——消费限额是授权上限，而非预先扣款。未使用的余额保留在你的钱包中。

## 单次使用卡

在创建时设置 `lockCardNextUse: true`（或通过 `editVirtualCard` 更新）可在首次授权后自动锁定该卡。建议在以下场景使用：

* 一次性供应商付款
* 单笔交易发放
* 需要在一次使用后即作废的智能代理支付流程

## 全部虚拟卡操作

| 操作                         | 类型       | 范围                                      | 页面                                                 |
| -------------------------- | -------- | --------------------------------------- | -------------------------------------------------- |
| 发现可用计划                     | Query    | `CREATE_VIRTUALCARD`                    | [获取虚拟卡优惠](/features/get-card-offers)               |
| 预先保存账单地址                   | Mutation | `CREATE_VIRTUALCARD`                    | [添加虚拟卡账单地址](/features/add-billing-address)         |
| 发行卡片                       | Mutation | `CREATE_VIRTUALCARD`                    | [创建虚拟卡](/features/create-card)                     |
| 获取 PAN、CVV、有效期             | Mutation | `REVEAL_VIRTUALCARD`                    | [展示虚拟卡](/recipes/reveal-virtual-card)              |
| 更新限额、昵称、锁定日期               | Mutation | `EDIT_VIRTUALCARD`                      | [编辑虚拟卡](/features/edit-virtual-card)               |
| 临时阻止消费                     | Mutation | `EDIT_VIRTUALCARD`                      | [锁定虚拟卡](/features/lock-virtual-card)               |
| 重新启用已锁卡片                   | Mutation | `EDIT_VIRTUALCARD`                      | [解锁虚拟卡](/features/unlock-virtual-card)             |
| 查询剩余余额（批量）                 | Query    | `REVEAL_VIRTUALCARD` + `PCI_COMPLIANCE` | [获取虚拟卡余额](/recipes/get-virtual-card-balance)       |
| 查看交易历史                     | Query    | `CREATE_VIRTUALCARD`                    | [获取虚拟卡交易](/features/get-virtual-card-transactions) |
| 批量发行卡（异步）                  | Mutation | `CREATE_VIRTUALCARD`                    | [批量操作](/features/create-bulk-order)                |
| 通过托管链接分发卡片                 | Mutation | `CREATE_SHARE_LINK`                     | [通过托管链接发送虚拟卡](/features/send-cards)                |
| 设置 PIN                     | Mutation | `EDIT_VIRTUALCARD`                      | [设置虚拟卡 PIN](/set-virtual-card-pin)                 |
| 推送到 Apple Pay / Google Pay | Mutation | —                                       | [数字钱包推送开卡](/digital-wallet-push-provisioning)      |
| 应用商户特定优惠                   | —        | —                                       | [卡片关联优惠](/features/card-linked-offers)             |
| 错误参考                       | —        | —                                       | [虚拟卡错误代码](/features/virtual-card-error-codes)      |

## 下一步

<Card title="创建你的第一张虚拟卡" icon="credit-card" horizontal href="/features/create-card">
  完整的 `createVirtualCard` 合同——输入、资金选项、消费控制与示例。
</Card>