> ## 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 軌道發行，可於線上或實體店面凡接受該網路之處使用。

卡片透過交換手續費機制，對所有消費賺取基礎**現金回饋**。在支援的商家，卡片連結優惠可再疊加額外回饋。

## 卡片類型

| Type                          | Description              |
| ----------------------------- | ------------------------ |
| **Standard Virtual Card**     | 適用於卡片網路上的所有商家            |
| **Brand-Locked Virtual Card** | 侷限於特定商家 — 適合目標性激勵計畫或消費控管 |

使用 [`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 呼叫。請參考 [Edit Virtual Card](/features/edit-virtual-card) 了解建立後如何修改此設定。

## 必要範圍（Scopes）

所有虛擬卡操作都需要以適當範圍產生的**使用者存取權杖**。三個核心範圍為：

| Scope                | Used By                                                               |
| -------------------- | --------------------------------------------------------------------- |
| `CREATE_VIRTUALCARD` | 建立卡片、取得方案、查餘額、查交易                                                     |
| `REVEAL_VIRTUALCARD` | 顯示 PAN、CVV 與到期日；同時在 `getVirtualCardBalance` 中需與 `PCI_COMPLIANCE` 一併使用 |
| `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` 時，請參考 [Refresh an Expired User Access Token](/get-started/refresh-expired-access-token)。

## 資金如何運作

當卡片被扣款時，Fluz 預設依下列優先順序撥款：

1. 指定的**消費帳戶**（`userCashBalanceId`）
2. **預付（禮品卡）餘額** — 除非設定 `usePrepaymentBalance: false`
3. **獎勵餘額** — 除非設定 `useRewardsBalance: false`

你也可以將 `primaryFundingSource: BANK_ACCOUNT` 設定為直接從**已連結的銀行帳戶**撥款。完整輸入細節與範例請見 [Create Virtual Card](/features/create-card)。

## 消費上限期間

你所設定的 `spendLimit` 會依選擇的 `spendLimitDuration` 套用：

| Duration   | Behavior       |
| ---------- | -------------- |
| `LIFETIME` | 橫跨卡片整個生命週期（預設） |
| `DAILY`    | 每個日曆日重置        |
| `WEEKLY`   | 每週重置           |
| `MONTHLY`  | 每月一日重置         |

你**只會被收取實際消費金額** — 消費上限是授權上限，而非預先扣款。未使用的餘額會留在你的錢包中。

## 單次使用卡

在建立時將 `lockCardNextUse: true` 設定（或透過 `editVirtualCard` 更新），可在首次授權後自動鎖卡。此為下列情境的建議做法：

* 一次性廠商付款
* 單筆交易的撥付
* 代理式支付流程中，卡片應於一次使用後即作廢的情境

## 所有虛擬卡操作

| Operation                  | Type     | Scope(s)                                | Page                                                                     |
| -------------------------- | -------- | --------------------------------------- | ------------------------------------------------------------------------ |
| 探索可用方案                     | Query    | `CREATE_VIRTUALCARD`                    | [Get Virtual Card Offers](/features/get-card-offers)                     |
| 預先儲存帳單地址                   | Mutation | `CREATE_VIRTUALCARD`                    | [Add Virtual Card Address](/features/add-billing-address)                |
| 發行卡片                       | Mutation | `CREATE_VIRTUALCARD`                    | [Create Virtual Card](/features/create-card)                             |
| 取得 PAN、CVV、到期日             | Mutation | `REVEAL_VIRTUALCARD`                    | [Reveal Virtual Card](/recipes/reveal-virtual-card)                      |
| 更新上限、暱稱、鎖定日期               | Mutation | `EDIT_VIRTUALCARD`                      | [Edit Virtual Card](/features/edit-virtual-card)                         |
| 暫時阻擋消費                     | Mutation | `EDIT_VIRTUALCARD`                      | [Lock Virtual Card](/features/lock-virtual-card)                         |
| 重新啟用已鎖卡片                   | Mutation | `EDIT_VIRTUALCARD`                      | [Unlock Virtual Card](/features/unlock-virtual-card)                     |
| 查詢剩餘餘額（批次）                 | Query    | `REVEAL_VIRTUALCARD` + `PCI_COMPLIANCE` | [Get Virtual Card Balance](/recipes/get-virtual-card-balance)            |
| 檢視交易歷史                     | Query    | `CREATE_VIRTUALCARD`                    | [Get Virtual Card Transactions](/features/get-virtual-card-transactions) |
| 批量發卡（非同步）                  | Mutation | `CREATE_VIRTUALCARD`                    | [Bulk Operations](/features/create-bulk-order)                           |
| 透過託管連結發卡                   | Mutation | `CREATE_SHARE_LINK`                     | [Send Hosted Links With Virtual Cards](/features/send-cards)             |
| 設定 PIN                     | Mutation | `EDIT_VIRTUALCARD`                      | [Set Virtual Card PIN](/set-virtual-card-pin)                            |
| 推送至 Apple Pay / Google Pay | Mutation | —                                       | [Digital Wallet Push Provisioning](/digital-wallet-push-provisioning)    |
| 套用特定商家優惠                   | —        | —                                       | [Card Linked Offers](/features/card-linked-offers)                       |
| 錯誤參考                       | —        | —                                       | [Virtual Card Error Codes](/features/virtual-card-error-codes)           |

## 下一步

<Card title="建立你的第一張虛擬卡" icon="credit-card" horizontal href="/features/create-card">
  完整的 `createVirtualCard` 合約 — 輸入、資金選項、消費控管與範例。
</Card>