> ## 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 中的每张卡、每笔购买与每次付款最终都依赖于此。

这里几乎所有你要构建的内容，都取决于三个问题：

* **这笔钱在哪个余额里？** 不同余额有不同规则——有的可提现，有的只能消费。
* **现金余额中的哪个消费账户？** 现金被分区到具名的子总账中，选择错误是最常见的意外失败来源。
* **资金是在流入、内部流转，还是流出？** 每个方向对应不同的变更，作用范围也不同。

***

## 四种余额

| 余额       | 资金来源                                | 可消费 | 可提现 | API 字段                |
| :------- | :---------------------------------- | :-: | :-: | :-------------------- |
| **现金余额** | 来自外部资金来源的存款                         |  ✓  |  ✓  | `cashBalance`         |
| **奖励余额** | 购物获得的返现                             |  ✓  |  ✓  | `rewardsBalance`      |
| **预付余额** | 存入 `GIFT_CARD_BALANCE`、兑换的 Fluz 礼品卡 |  ✓  |  ✗  | `giftCardCashBalance` |
| **预留余额** | 存入 `RESERVE_BALANCE`                |  —  |  ✗  | —                     |

### 现金余额

工作余额。由存款补充，用于购买礼品卡与虚拟卡，可提现到外部账户。它不是一个单独的池子——而是**你的消费账户的聚合**，详见下一节。

### 奖励余额

购物获得的返现。完全可提现，也完全可消费。不同于现金余额与预付余额，它不包含待结算金额，因为奖励是在获得时即入账，而非分期结算。

通过传入 `source: "REWARDS_BALANCE"` 提现——这是除现金外 `withdrawCashBalance` 接受的唯一余额。

### 预付余额

<Note>
  **一个余额，四个名字。** 产品称其为**预付余额**。API 字段是 `giftCardCashBalance`，存款枚举是 `GIFT_CARD_BALANCE`，部分页面仍称其为“礼品卡余额”。这些都指同一件事。
</Note>

仅可消费。你可以通过两种方式为其充值——使用 `depositType: "GIFT_CARD_BALANCE"` 进行存款，或兑换一张 Fluz 礼品卡代码——并可用于消费，但**永远不能提现到外部账户。** 进入预付余额的资金，只能通过消费离开。

这是一种产品设计，而非限制：它是预付价值，因此将存入视为一种承诺。如果你可能需要把资金取出，请改为存入现金余额。

### 预留余额

通过 `depositType: "RESERVE_BALANCE"` 存入，并作为预留资金持有。不可提现。

***

## 消费账户

**消费账户**是现金余额下的具名子总账——例如“运营”“团队差旅”“客户 A”——它们各自拥有余额，且归属于同一个 Fluz 账户。

<Note>
  **“消费账户”“现金余额”和 `UserCashBalance` 指的是同一对象。** 产品将其呈现为消费账户；API 类型是 `UserCashBalance`，因此字段为 `userCashBalanceId`、`availableCashBalance` 等等。

  不要与 `bankAccountId` 混淆，后者指的是外部已链接的银行账户。
</Note>

每个账户都有一个**默认**消费账户。未指明消费账户的存款、购买与卡片资金补充，都会落到被标记为 `isDefault` 的那个账户。

<Warning>
  **如果你持有多个消费账户，请在每次操作中明确指定。** 依赖默认账户是导致意外“资金不足”失败的首要原因——新的存款路由到了别处，或默认账户标记被更改，都会在你的代码不变的情况下悄然改变资金来源。
</Warning>

### 三个数字

每个消费账户都会跟踪三个金额，它们回答不同问题：

| 字段                     | 回答的问题                      |
| :--------------------- | :------------------------- |
| `availableCashBalance` | 现在我能**立刻**花多少钱？            |
| `totalCashBalance`     | 账户里共有多少，包括尚不可用的金额？         |
| `lifetimeCashBalance`  | 这里**曾经**存入过多少？只增不减——用于审计踪迹 |

在任何批量操作前检查 `availableCashBalance`。`totalCashBalance` 减去可用金额，即为在途资金。

### 管理方式

| 操作   | 变更                                       |
| :--- | :--------------------------------------- |
| 创建   | `createUserCashBalance` — 接收 `nickname`  |
| 列表   | `getUserCashBalances` — 可过滤、可分页          |
| 读取单个 | `getUserCashBalanceById`                 |
| 重命名  | [编辑消费账户](/features/edit-spend-accounts)  |
| 关闭   | [关闭消费账户](/features/close-spend-accounts) |

→ [消费账户](/features/spend-accounts) · [获取消费账户](/features/get-spend-accounts)

***

## 资金流转的所有方式

| 来自         | 流向             | 变更                                         | Scope                    |
| :--------- | :------------- | :----------------------------------------- | :----------------------- |
| 外部资金来源     | 现金余额 / 消费账户    | `depositCashBalance` — `CASH_BALANCE`      | `MAKE_DEPOSIT`           |
| 外部资金来源     | 预付余额           | `depositCashBalance` — `GIFT_CARD_BALANCE` | `MAKE_DEPOSIT`           |
| 外部资金来源     | 预留余额           | `depositCashBalance` — `RESERVE_BALANCE`   | `MAKE_DEPOSIT`           |
| Fluz 礼品卡代码 | 预付余额           | `redeemFluzGiftCard`                       | `MAKE_DEPOSIT`           |
| 你的消费账户     | 你的另一个消费账户      | `transferInternalBalance`                  | `MAKE_INTERNAL_TRANSFER` |
| 你的账户       | 另一位 Fluz 用户的账户 | `createTransfer`                           | —                        |
| 现金或奖励余额    | 外部账户           | `withdrawCashBalance`                      | `MAKE_WITHDRAWAL`        |
| 购买         | 奖励余额           | 自动获得                                       | —                        |

### 流入 — 来自外部来源的存款

`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 礼品卡

`redeemFluzGiftCard` 将一枚 Fluz 礼品卡**代码**直接记入预付余额。兑换是即时完成的，任何激活费用会在 `depositFee` 中返回。

这是无需绑定资金来源就能为钱包注入价值的唯一方式——适用于促销、返利与赠礼，收件人甚至可能完全未绑定银行账户。

→ [兑换 Fluz 礼品卡](/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` 指定你自己的标识符——参见 [管理外部引用 ID](/managing-external-reference-ids)。收款人必须已授权你的应用。

→ [账户到账户转账](/features/account-to-account-transfers) · [收款人查询](/features/lookup-recipient)

### 流出 — 提现至外部账户

`withdrawCashBalance` 将资金转出。选择一个**来源余额**——`CASH_BALANCE` 或 `REWARDS_BALANCE`，这两者是唯二支持提现的余额——以及一种**方式**，并提供相匹配的目标 ID：

| 方式          | 必填字段             | 时间与费用                          |
| :---------- | :--------------- | :----------------------------- |
| `BANK_ACH`  | `bankAccountId`  | 1–3 个工作日，无费用                   |
| `BANK_CARD` | `bankCardId`     | 向符合条件的借记卡发起 Push-to-card，可能有费用 |
| `PAYPAL`    | `paypalVaultId`  | 可能有费用                          |
| `VENMO`     | `venmoAccountId` | 可能有费用                          |

当来源为现金余额时，请指明要扣款的消费账户。对 ACH 来说，预期初始状态为 `PENDING` 或 `PROCESSING`，而非立即完成。

<Note>
  提现输入中将消费账户字段命名为 `cashBalanceId`，而存款与购买使用 `userCashBalanceId`。同一对象，不同字段名——这是一个已知的不一致点，需要留意。
</Note>

→ [提现到外部账户](/features/withdraw-to-external-account)

***

## 读取余额

两个查询，两个粒度：

| 查询                    | 返回                                                                                            |
| :-------------------- | :-------------------------------------------------------------------------------------------- |
| `getWallet`           | 所有余额——`cashBalance`、`rewardsBalance`、`giftCardCashBalance`——外加已链接的资金来源与 `blockedPaymentTypes` |
| `getUserCashBalances` | 按消费账户的详细信息：昵称、`isDefault`、状态，以及三个金额                                                           |

`getWallet` 也是你获取每次存款与提现所需资金来源 ID 的位置。在移动资金前检查余额，而不是在失败后再处理。

→ [检查账户余额](/check-account-balance) · [查看资金来源](/features/view-funding-sources)

***

## 幂等性

每一次资金变动——存款、兑换、内部转账、账户间转账、提现——都需要一个唯一的、由客户端生成的 `idempotencyKey`。

重复提交相同的 key 会返回原始结果，而不会再次处理。**每个“预期的资金移动”生成一个 key，并在该移动的所有重试中复用它。** 在重试时换用新的 key，则可能造成重复转账。

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

***

## Scopes

| Scope                    | 覆盖范围            |
| :----------------------- | :-------------- |
| `LIST_PAYMENT`           | 读取钱包、余额与资金来源    |
| `MANAGE_PAYMENT`         | 创建与管理消费账户与资金来源  |
| `MAKE_DEPOSIT`           | 存款与 Fluz 礼品卡兑换  |
| `MAKE_INTERNAL_TRANSFER` | 在你自己的消费账户之间划转资金 |
| `MAKE_WITHDRAWAL`        | 向外部账户发送资金       |

请先在你应用的**Permissions**选项卡中启用这些 scope——未启用却在请求中声明的 scope 会被静默丢弃而非拒绝。→ [配置 OAuth 应用](/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>