> ## 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 餘額、消費帳戶如何分割現金餘額，以及資金在錢包內外移動的所有方式。

一個 Fluz 錢包包含兩部分：一組持有價值的**餘額**，以及一組**連結到外部帳戶**、用來將價值轉入與轉出的連結。API 其餘各處的每張卡、每筆消費與每次撥款最終都依賴於此。

幾個關鍵問題幾乎決定了你在這裡要建構的一切：

* **這筆錢在哪個餘額中？** 每個餘額規則不同——有些可提領，有些只能消費。
* **在現金餘額中的哪個消費帳戶？** 現金被分割成具名的次分類帳。選錯帳戶是最常見的失敗原因。
* **資金是往內、在內部移動，還是往外？** 每個方向都是不同的變更，範圍也不同。

***

## 四種餘額

| Balance                | Funded by                                                 | Spendable | Withdrawable | API field             |
| :--------------------- | :-------------------------------------------------------- | :-------: | :----------: | :-------------------- |
| **Cash balance**       | Deposits from external funding sources                    |     ✓     |       ✓      | `cashBalance`         |
| **Rewards balance**    | Cashback earned on purchases                              |     ✓     |       ✓      | `rewardsBalance`      |
| **Prepayment balance** | Deposits to `GIFT_CARD_BALANCE`, redeemed Fluz Gift Cards |     ✓     |       ✗      | `giftCardCashBalance` |
| **Reserve balance**    | Deposits to `RESERVE_BALANCE`                             |     —     |       ✗      | —                     |

### Cash balance

工作用的餘額。由存款補充，花費於禮品卡與虛擬卡，可提領到外部帳戶。它不是單一池子——而是**你的消費帳戶的總和**，下一節將介紹。

### Rewards balance

購買所賺取的現金回饋。可完全提領且可完全消費。不同於現金與預付餘額，它不帶有待入帳金額，因為回饋在賺取時即入帳，而不是隨時間結算。

要從該餘額提領，請傳入 `source: "REWARDS_BALANCE"`——除了現金餘額外，`withdrawCashBalance` 唯一接受的餘額。

### Prepayment balance

<Note>
  **一種餘額，四個名稱。** 在產品層面稱為 **prepayment balance（預付餘額）**。API 欄位是 `giftCardCashBalance`，存款列舉值是 `GIFT_CARD_BALANCE`，且有些頁面仍稱為「gift card balance」。都是同一件事。
</Note>

僅能消費。你可以用兩種方式補充——`depositType: "GIFT_CARD_BALANCE"` 的存款，或兌換 Fluz Gift Card 代碼——也可以用於消費，但**它永遠不能提領到外部帳戶。** 進入預付餘額的資金只能透過消費離開。

這是設計重點，而非限制：它是預付價值，因此將其存入視為一種承諾。如果你可能需要將資金轉回，請改存入現金餘額。

### Reserve balance

透過 `depositType: "RESERVE_BALANCE"` 存入，並加以保留。不允許提領。

***

## Spend accounts

**消費帳戶**是現金餘額底下的具名次分類帳——例如「Operations」、「Team Travel」、「Client A」——同屬一個 Fluz 帳戶之下，各自擁有其餘額。

<Note>
  **「Spend account」、「cash balance」與 `UserCashBalance` 指的是相同物件。** 產品層面呈現為消費帳戶；API 型別是 `UserCashBalance`，因此欄位為 `userCashBalanceId`、`availableCashBalance` 等。

  請不要與 `bankAccountId` 混淆，後者指的是「外部」已連結的銀行帳戶。
</Note>

每個帳戶都有一個**預設**消費帳戶。未指名帳戶的存款、購買與卡片資金補充都會落到被標記為 `isDefault` 的那一個。

<Warning>
  **如果你持有多個消費帳戶，請在每個操作中明確指定。** 依賴預設帳戶是導致「餘額不足」異常的最常見原因——新的存款被導向其他處，或預設旗標變更，會在你程式碼不變的情況下默默改變資金來源。
</Warning>

### 三個數字

每個消費帳戶追蹤三個金額，它們回答不同的問題：

| Field                  | Question it answers        |
| :--------------------- | :------------------------- |
| `availableCashBalance` | 我**現在**可以花多少？              |
| `totalCashBalance`     | 帳戶裡共有多少（含尚未可用的金額）？         |
| `lifetimeCashBalance`  | 這裡**曾經**存入過多少？只會成長——作為稽核紀錄 |

在任何大量操作前先檢查 `availableCashBalance`。`totalCashBalance` 減去 available 即為在途中流動的金額。

### 管理它們

| Operation | Mutation                                 |
| :-------- | :--------------------------------------- |
| Create    | `createUserCashBalance` — 需提供 `nickname` |
| List      | `getUserCashBalances` — 可篩選與分頁           |
| Read one  | `getUserCashBalanceById`                 |
| Rename    | [編輯消費帳戶](/features/edit-spend-accounts)  |
| Close     | [關閉消費帳戶](/features/close-spend-accounts) |

→ [消費帳戶](/features/spend-accounts) · [取得消費帳戶](/features/get-spend-accounts)

***

## 資金移動的所有方式

| From                    | To                             | Mutation                                   | Scope                    |
| :---------------------- | :----------------------------- | :----------------------------------------- | :----------------------- |
| External funding source | Cash balance / spend account   | `depositCashBalance` — `CASH_BALANCE`      | `MAKE_DEPOSIT`           |
| External funding source | Prepayment balance             | `depositCashBalance` — `GIFT_CARD_BALANCE` | `MAKE_DEPOSIT`           |
| External funding source | Reserve balance                | `depositCashBalance` — `RESERVE_BALANCE`   | `MAKE_DEPOSIT`           |
| Fluz Gift Card code     | Prepayment balance             | `redeemFluzGiftCard`                       | `MAKE_DEPOSIT`           |
| Your spend account      | Another of your spend accounts | `transferInternalBalance`                  | `MAKE_INTERNAL_TRANSFER` |
| Your account            | Another Fluz user's account    | `createTransfer`                           | —                        |
| Cash or rewards balance | External account               | `withdrawCashBalance`                      | `MAKE_WITHDRAWAL`        |
| Purchases               | Rewards balance                | Earned automatically                       | —                        |

### 轉入 — 從外部來源存入

`depositCashBalance` 從已連結的資金來源提取資金，存入你選擇的餘額。

* **資金來源：** `bankAccountId`、`bankCardId` 或 `paypalVaultId`，皆可從 `getWallet` 取得。
* **目的地：** `depositType` 可為 `CASH_BALANCE`、`GIFT_CARD_BALANCE` 或 `RESERVE_BALANCE`。
* **消費帳戶：** 使用 `CASH_BALANCE` 時，請以 `userCashBalanceId` 明確指定目標帳戶。

結算時間依來源不同，從即時到 2–5 個工作天不等。回傳的 `balances` 物件反映可即時使用的金額，因此請讀取它，而不要假設全額已入帳。

→ [從外部帳戶存入資金](/features/deposit-from-external-accounts) · [資金來源](/features/funding-sources)

### 轉入 — 兌換 Fluz Gift Card

`redeemFluzGiftCard` 將 Fluz Gift Card 的**代碼**直接入帳至預付餘額。兌換是即時的，任何啟用費將回傳在 `depositFee`。

這是唯一一種在沒有連結資金來源的情況下，將價值存入錢包的方法——適用於促銷、回扣與贈禮，受贈者可能完全沒有連結任何銀行帳戶。

→ [兌換 Fluz Gift Card](/features/redeem-fluz-gift-card)

### 內部移轉 — 在你自己的消費帳戶之間

`transferInternalBalance` 在你擁有的兩個消費帳戶之間移動資金。內部會被記錄為兩個關聯動作——來源帳戶的提領與目的帳戶的存入——回應會同時回傳兩者。

```json theme={null}
{
  "input": {
    "idempotencyKey": "1f1df3e7-5d43-4e3d-83de-31922d4aefb7",
    "amount": 25.00,
    "sourceUserCashBalanceId": "<SOURCE_ACCOUNT_ID>",
    "destinationUserCashBalanceId": "<DESTINATION_ACCOUNT_ID>"
  }
}
```

兩個 ID 都必須是你自己的帳戶，且不可相同，來源帳戶需有足夠的「可用」餘額。內部移轉會立即結算——這使它成為在購買被錯誤帳戶扣款時，最快速解鎖的方式。

→ [在消費帳戶間移轉](/features/transfer-between-spend-accounts)

### 內部移轉 — 轉給另一個 Fluz 使用者

轉給「不同」的 Fluz 帳戶是另一個操作。可用 `accountId` 指定目的地，或用你自己的識別碼 `externalReferenceId`——請見[管理 External Reference ID](/managing-external-reference-ids)。收款方必須已授權你的應用程式。

→ [帳戶對帳戶轉帳](/features/account-to-account-transfers) · [收款方查找](/features/lookup-recipient)

### 轉出 — 提領至外部帳戶

`withdrawCashBalance` 將資金轉出。選擇**來源餘額**——`CASH_BALANCE` 或 `REWARDS_BALANCE`，這兩者是唯一支援提領的餘額——與**方法**，並提供相對應的目的地 ID：

| Method      | Required field   | Timing and cost      |
| :---------- | :--------------- | :------------------- |
| `BANK_ACH`  | `bankAccountId`  | 1–3 個工作天，無手續費        |
| `BANK_CARD` | `bankCardId`     | 推送至符合資格的簽帳金融卡，可能有手續費 |
| `PAYPAL`    | `paypalVaultId`  | 可能有手續費               |
| `VENMO`     | `venmoAccountId` | 可能有手續費               |

當來源是現金餘額時，請指定要扣款的消費帳戶。ACH 通常先呈現 `PENDING` 或 `PROCESSING` 狀態，而非立即完成。

<Note>
  提領的輸入欄位將消費帳戶命名為 `cashBalanceId`，而存款與購買則使用 `userCashBalanceId`。同一個物件，不同的欄位名稱——已知的不一致，請留意。
</Note>

→ [提領至外部帳戶](/features/withdraw-to-external-account)

***

## 讀取餘額

兩個查詢、兩種粒度：

| Query                 | Returns                                                                                       |
| :-------------------- | :-------------------------------------------------------------------------------------------- |
| `getWallet`           | 所有餘額——`cashBalance`、`rewardsBalance`、`giftCardCashBalance`——以及已連結的資金來源與 `blockedPaymentTypes` |
| `getUserCashBalances` | 逐一消費帳戶的詳細資料：暱稱、`isDefault`、狀態與三個金額                                                            |

`getWallet` 也是你取得每次存入與提領所需資金來源 ID 的地方。移動資金前先檢查餘額，而不是等到失敗再處理。

→ [檢查帳戶餘額](/check-account-balance) · [檢視資金來源](/features/view-funding-sources)

***

## 冪等性

每個資金移動的變更——存款、兌換、內部移轉、帳戶對帳戶轉帳、提領——都需要一個唯一且由用戶端產生的 `idempotencyKey`。

以相同 key 重送請求會回傳原結果，而不會再次處理。**為每一次預期的資金移動產生一個 key，並在該次移動的每次重試都重用它。** 為重試產生新 key 會導致重複轉帳。

→ [冪等性](/concepts/idempotency)

***

## Scopes

| Scope                    | Covers                |
| :----------------------- | :-------------------- |
| `LIST_PAYMENT`           | 讀取錢包、餘額與資金來源          |
| `MANAGE_PAYMENT`         | 建立與管理消費帳戶與資金來源        |
| `MAKE_DEPOSIT`           | 存款與 Fluz Gift Card 兌換 |
| `MAKE_INTERNAL_TRANSFER` | 在你自己的消費帳戶之間移動資金       |
| `MAKE_WITHDRAWAL`        | 將資金轉出至外部帳戶            |

請先在你應用程式的「Permissions」分頁啟用這些範圍——若你請求了未啟用的 scope，系統會靜默忽略而非拒絕。→ [設定 OAuth App](/configure-o-auth-app)

***

## 下一步

<CardGroup cols={2}>
  <Card title="透過錢包移動資金" icon="play" href="/quickstart/move-money-through-a-wallet">
    從頭到尾的完整生命週期，可直接執行的快速上手。
  </Card>

  <Card title="消費帳戶" icon="wallet" href="/features/spend-accounts">
    建立、資金補充、重新命名與關閉次分類帳。
  </Card>

  <Card title="資金來源" icon="link" href="/features/funding-sources">
    連結銀行卡、銀行帳戶與數位錢包。
  </Card>

  <Card title="存入資金" icon="banknote-arrow-down" href="/features/deposit-from-external-accounts">
    完整的存款輸入參考。
  </Card>

  <Card title="提領資金" icon="banknote-arrow-up" href="/features/withdraw-to-external-account">
    方法、時間與錯誤處理。
  </Card>

  <Card title="交易活動" icon="receipt" href="/features/get-all-transactions">
    將所有移動匯整於一個可篩選的資訊流。
  </Card>
</CardGroup>