> ## 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 上的每一美元都存放于一个**余额**中。资金从外部资金来源或虚拟账户号码进入余额，通过转账在余额之间流动，并通过购买或提现离开。本节涵盖以上全部内容。

首先要理解的最有用的一点：**一个账户不只有一个余额。它有多个，而且它们的行为各不相同。** 有些可提现，有些不可提现，其中一个——消费账户——可以存在多个。

***

## 资金地图

```mermaid theme={null}
flowchart LR
    subgraph IN["Money In"]
        F1["Bank account (ACH)"]
        F2["Bank card"]
        F3["PayPal / Apple Pay"]
        F4["Virtual account number\nRTP · FedNow · Wire · ACH"]
        F5["Fluz gift card redemption"]
        F6["Cashback earned"]
    end

    subgraph BAL["Balances"]
        SA1["Spend Account\n'Operations'"]
        SA2["Spend Account\n'Team Travel'"]
        RW["Rewards Balance"]
        GC["Gift Card Balance\nnon-withdrawable"]
        RS["Reserve Balance\nnon-withdrawable"]
    end

    subgraph OUT["Money Out"]
        O1["Gift card purchases"]
        O2["Virtual card funding"]
        O3["Transfers to other\nFluz accounts"]
        O4["Withdrawals to\nexternal accounts"]
    end

    F1 & F2 & F3 --> SA1
    F4 --> SA1
    F4 --> SA2
    F5 --> GC
    F6 --> RW

    SA1 & SA2 --> O1 & O2 & O3 & O4
    RW --> O1 & O4
    GC --> O1 & O2
    RS -.->|covers failed settlement| O1
```

***

## 余额类型

一个账户最多可以持有四种余额。消费账户是唯一一种用户可以拥有多个的余额。

| 余额             | 可否提现 | 它包含什么                           |
| -------------- | ---- | ------------------------------- |
| **消费账户**（现金余额） | 可    | 主要的工作余额。用于为礼品卡、虚拟卡、转账和提现提供资金。   |
| **奖励余额**       | 可    | 在 Fluz 活动中赚取的返现和奖励奖金。           |
| **礼品卡余额**      | 否    | 预付价值，仅可用于礼品卡和虚拟卡购买。             |
| **准备金余额**      | 否    | 由 Fluz 持有，用于覆盖结算失败的交易，保持账户良好状态。 |

这些余额之和构成账户的**可用 Fluz 余额**——可用于为支付提供资金的总额。

<Note>
  **同一余额会以多个名称出现。**

  礼品卡余额在 `getWallet` 中返回为 `giftCardCashBalance`，在 `Transaction` 类型上返回为 `gift_card_prepayment_balance_*`。奖励余额在 `getWallet` 中是 `rewardsBalance`，在 `Transaction` 上是 `seat_balance_*`。这些是别名，而不是不同的钱包。
</Note>

***

## 消费账户持有余额

[消费账户](/features/spend-accounts)——API 中的 `UserCashBalance`——是一个具名的现金容器。用户可以开设多个，并为每个设置昵称，从而按用途隔离资金而无需开设多个 Fluz 账户。

**每个消费账户都有自己独立的余额。** 一个账户中的资金不会在另一个账户中可用，除非通过[内部转账](/features/transfer-between-spend-accounts)进行划转。

```mermaid theme={null}
flowchart TD
    ACC["Fluz Account"]

    ACC --> RW["Rewards Balance\naccount-level, one only"]
    ACC --> GC["Gift Card Balance\naccount-level, one only"]
    ACC --> RS["Reserve Balance\naccount-level, one only"]
    ACC --> SAS["Spend Accounts\none or many"]

    SAS --> S1["'Operations'\ntotal · available · lifetime\n+ virtual account numbers"]
    SAS --> S2["'Team Travel'\ntotal · available · lifetime\n+ virtual account numbers"]
    SAS --> S3["'Marketing'\ntotal · available · lifetime\n+ virtual account numbers"]

    S1 <-->|internal transfer| S2
    S2 <-->|internal transfer| S3
```

每个消费账户跟踪三个数值，均以字符串返回：

| 字段                     | 含义              |
| ---------------------- | --------------- |
| `totalCashBalance`     | 该账户当前持有的全部余额。   |
| `availableCashBalance` | 目前可立即支用的部分。     |
| `lifetimeCashBalance`  | 该账户自成立以来累计存入总额。 |

***

## 入金方式

资金流入余额有两种本质不同的方向，这一区别会影响你的集成方式。

<CardGroup cols={2}>
  <Card title="拉取——由你发起" icon="arrow-down">
    你的应用调用 `depositCashBalance`，Fluz 从用户已关联的**资金来源**拉取资金：银行账户、银行卡或数字钱包。你可控制时间与金额。
  </Card>

  <Card title="推送——由他方发起" icon="arrow-right-to-bracket">
    外部方将资金发送至附属于某个消费账户的**虚拟账户号码**。到达后 Fluz 记入存款。你无法控制时间与金额。
  </Card>
</CardGroup>

| 路径                                               | 支付轨道                      | 发起方   | 入账至           |
| ------------------------------------------------ | ------------------------- | ----- | ------------- |
| [存入资金](/features/deposit-from-external-accounts) | ACH 拉取、银行卡、PayPal         | 你的应用  | 指定的消费账户       |
| [虚拟账户号码](/features/virtual-account-numbers)      | RTP、FedNow、Wire、电汇、ACH 入账 | 外部汇款方 | 该 VAN 背后的消费账户 |
| [兑换 Fluz 礼品卡](/features/redeem-fluz-gift-card)   | —                         | 用户    | 礼品卡余额         |
| 符合条件活动的返现                                        | —                         | Fluz  | 奖励余额          |

<Note>
  **虚拟账户号码是一个地址，而非余额。**

  每个消费账户可以拥有一个或多个虚拟账户号码——真实的路由号与账号对。任何汇入这些号码的资金都会记入该消费账户。同一账户上的多个 VAN 共享同一余额；它们的存在是为了让你区分不同来款，如工资入账与客户付款。参见[虚拟账户号码](/features/virtual-account-numbers)。
</Note>

***

## 资金划转与取出

| 动作                                                    | 操作              | 所需权限             |
| ----------------------------------------------------- | --------------- | ---------------- |
| [在消费账户间转账](/features/transfer-between-spend-accounts) | 内部转账            | `MANAGE_PAYMENT` |
| [转账至其他 Fluz 账户](/features/application-transfer)       | 钱包转账            | `MANAGE_PAYMENT` |
| [查询转账收款人](/features/lookup-recipient)                 | 解析 `account_id` | —                |
| [提现至外部账户](/features/withdraw-funds)                   | 提现              | `MANAGE_PAYMENT` |

<Warning>
  **礼品卡余额与准备金余额不可提现。** 礼品卡余额仅可用于礼品卡与虚拟卡购买。准备金余额由 Fluz 持有，非用户可指挥的资金。
</Warning>

***

## 读取余额

`getWallet` 一次性返回账户的各类余额，以及用户已关联的资金来源。

```graphql theme={null}
query getWallet {
  getWallet {
    balances {
      rewardsBalance      { availableBalance totalBalance lifetimeBalance }
      cashBalance         { availableBalance totalBalance pendingBalance lifetimeBalance }
      giftCardCashBalance { availableBalance totalBalance pendingBalance lifetimeBalance }

      userCashBalances(paginate: { limit: 10, offset: 0 }) {
        userCashBalanceId
        nickname
        totalCashBalance
        availableCashBalance
        lifetimeCashBalance
        status
        createdAt
      }
    }
    blockedPaymentTypes
  }
}
```

`userCashBalances` 支持分页，并按创建时间倒序返回账户。若要获取单个消费账户，请使用 [`getUserCashBalanceById`](/features/get-spend-accounts)。

<Warning>
  **若需展示用户可支用现金总额，请对 `userCashBalances` 中的 `availableCashBalance` 求和。** 不要再将 `cashBalance` 与各个消费账户数值相加——那会高估总额。
</Warning>

准备金余额由 Fluz 持有而非用户指挥。其当前状态可在每笔交易上通过 `reserve_balance_available_balance` 和 `reserve_balance_total_balance` 快照字段查看，详见下文。

***

## 读取总账

余额告诉你现状；`getTransactions` 告诉你如何到达该状态。若要查看某个特定消费账户的总账，请按其 ID 过滤。

**所需权限范围：** `LIST_PAYMENT` **以及** `LIST_PURCHASES`

```graphql theme={null}
query spendAccountLedger($userCashBalanceId: [UUID], $limit: Int, $offset: Int) {
  getTransactions(
    filter: { userCashBalanceId: $userCashBalanceId }
    paginate: { limit: $limit, offset: $offset }
  ) {
    transactions {
      record_id
      transaction_type
      amount
      source
      destination
      status
      used_user_cash_balance_id
      cash_balance_available_balance
      created_at
    }
    totalCount
    hasNextPage
  }
}
```

```json Variables theme={null}
{
  "userCashBalanceId": ["9c1f6b2e-4d7a-4c3b-9f11-2a5e8b0d6c74"],
  "limit": 20,
  "offset": 0
}
```

每笔交易还带有一个**余额快照**——该交易应用后每个余额的状态——以及指示交易影响了哪些余额的标志位：

| 余额    | 快照字段                                                                                            | 影响标志                            |
| ----- | ----------------------------------------------------------------------------------------------- | ------------------------------- |
| 消费/现金 | `cash_balance_available_balance` · `cash_balance_total_balance`                                 | `is_cash_balance_affected`      |
| 奖励    | `seat_balance_available_balance` · `seat_balance_total_balance`                                 | `is_seat_balance_affected`      |
| 礼品卡   | `gift_card_prepayment_balance_available_balance` · `gift_card_prepayment_balance_total_balance` | `is_gift_card_balance_affected` |
| 准备金   | `reserve_balance_available_balance` · `reserve_balance_total_balance`                           | `is_reserve_balance_affected`   |
| 其他现金  | `other_cash_balance_available_balance` · `other_cash_balance_total_balance`                     | —                               |

<Note>
  **只有消费账户可按 ID 过滤。** `TransactionFilterInput` 暴露了 `userCashBalanceId`，但没有针对奖励、礼品卡或准备金余额的等效过滤器。若要筛选这些余额的活动，请按日期范围获取交易并基于相应的 `is_..._affected` 标志过滤。
</Note>

`getTransactions` 每页最多返回**20 条记录**。检查 `hasNextPage` 并递增 `offset` 以分页。完整过滤器参考见 [Get All Transactions](/features/get-all-transactions)。

***

## 权限范围速览

| 你的目标           | 所需范围                              |
| -------------- | --------------------------------- |
| 读取余额、消费账户与 VAN | `LIST_PAYMENT`                    |
| 读取交易总账         | `LIST_PAYMENT` + `LIST_PURCHASES` |
| 创建、编辑或关闭消费账户   | `MANAGE_PAYMENT`                  |
| 存入、转账或提现       | `MANAGE_PAYMENT`                  |

***

## 下一步去哪里

<CardGroup cols={2}>
  <Card title="消费账户" icon="wallet" href="/features/spend-accounts">
    创建、重命名并关闭持有余额的账户。
  </Card>

  <Card title="虚拟账户号码" icon="building-columns" href="/features/virtual-account-numbers">
    通过 RTP、FedNow、电汇与 ACH 入账直接接收至消费账户。
  </Card>

  <Card title="存入资金" icon="arrow-down-to-line" href="/features/deposit-from-external-accounts">
    从已关联的银行账户或银行卡拉取资金入金。
  </Card>

  <Card title="提现资金" icon="arrow-up-from-line" href="/features/withdraw-funds">
    将资金转出至外部账户。
  </Card>

  <Card title="账户间转账" icon="right-left" href="/features/transfer-between-spend-accounts">
    在用户自己的多个消费账户之间划转余额。
  </Card>

  <Card title="获取全部交易" icon="list" href="/features/get-all-transactions">
    完整总账，包含过滤与分页。
  </Card>
</CardGroup>

***

**想了解更多？** 与我们的专家交流以获取更多信息或申请演示。