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

***

## 餘額類型

一個帳戶最多可持有四種餘額。消費帳戶是唯一可讓使用者擁有多個的類型。

| Balance                          | Withdrawable | What it holds                   |
| -------------------------------- | ------------ | ------------------------------- |
| **Spend account** (cash balance) | Yes          | 主要的作業餘額。可用於禮品卡、虛擬卡、轉帳與提領。       |
| **Rewards balance**              | Yes          | 在 Fluz 活動中獲得的現金回饋與獎勵。           |
| **Gift card balance**            | No           | 僅可用於購買禮品卡與虛擬卡的預付金額。             |
| **Reserve balance**              | No           | 由 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
```

每個消費帳戶會追蹤三個數值，皆以字串回傳：

| Field                  | Meaning       |
| ---------------------- | ------------- |
| `totalCashBalance`     | 目前帳戶內持有的全部餘額。 |
| `availableCashBalance` | 此刻可立即支用的部分。   |
| `lifetimeCashBalance`  | 此帳戶歷來累計存入的總額。 |

***

## 入金方式

資金進入餘額主要有兩種方向，且在建置時此區別相當重要。

<CardGroup cols={2}>
  <Card title="拉取（由你發起）" icon="arrow-down">
    你的應用程式呼叫 `depositCashBalance`，Fluz 從使用者已連結的**資金來源**拉取資金：銀行帳戶、銀行卡或行動錢包。你可控管時間與金額。
  </Card>

  <Card title="推送（由他方發起）" icon="arrow-right-to-bracket">
    外部方將資金匯入連結於消費帳戶的**虛擬帳號**。資金抵達時，Fluz 會入帳為存款。你無法控制時間與金額。
  </Card>
</CardGroup>

| Path                                                        | Rails                         | Initiated by | Lands in      |
| ----------------------------------------------------------- | ----------------------------- | ------------ | ------------- |
| [Deposit funds](/features/deposit-from-external-accounts)   | ACH pull, card, PayPal        | Your app     | 指定的消費帳戶       |
| [Virtual account number](/features/virtual-account-numbers) | RTP, FedNow, Wire, ACH credit | 外部匯入者        | 該 VAN 背後的消費帳戶 |
| [Redeem a Fluz gift card](/features/redeem-fluz-gift-card)  | —                             | 使用者          | 禮品卡餘額         |
| Cashback on qualifying activity                             | —                             | Fluz         | 回饋餘額          |

<Note>
  **虛擬帳號是地址，不是餘額。**

  每個消費帳戶可擁有一個或多個虛擬帳號——真實的匯款路由與帳號組合。匯入到這些帳號的任何資金都會入帳至該消費帳戶。同一帳戶上的多個 VAN 都匯入同一餘額；它們存在的目的，是讓你能分辨例如薪資入帳與客戶付款。參見 [Virtual Account Numbers](/features/virtual-account-numbers)。
</Note>

***

## 移動與移除資金

| Action                                                                       | Operation               | Scope            |
| ---------------------------------------------------------------------------- | ----------------------- | ---------------- |
| [Transfer between spend accounts](/features/transfer-between-spend-accounts) | Internal transfer       | `MANAGE_PAYMENT` |
| [Transfer to another Fluz account](/features/application-transfer)           | Wallet transfer         | `MANAGE_PAYMENT` |
| [Look up a transfer recipient](/features/lookup-recipient)                   | Resolve an `account_id` | —                |
| [Withdraw to an external account](/features/withdraw-funds)                  | Withdrawal              | `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 篩選。

**所需範圍（Scopes）：** `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
}
```

每筆交易也都包含一個**餘額快照**——該交易入帳之後各餘額的狀態——以及指出該交易影響了哪些餘額的旗標：

| Balance      | Snapshot fields                                                                                 | Affected flag                   |
| ------------ | ----------------------------------------------------------------------------------------------- | ------------------------------- |
| Spend / cash | `cash_balance_available_balance` · `cash_balance_total_balance`                                 | `is_cash_balance_affected`      |
| Rewards      | `seat_balance_available_balance` · `seat_balance_total_balance`                                 | `is_seat_balance_affected`      |
| Gift card    | `gift_card_prepayment_balance_available_balance` · `gift_card_prepayment_balance_total_balance` | `is_gift_card_balance_affected` |
| Reserve      | `reserve_balance_available_balance` · `reserve_balance_total_balance`                           | `is_reserve_balance_affected`   |
| Other cash   | `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)。

***

## 權限範圍一覽

| You want to…   | Scope                             |
| -------------- | --------------------------------- |
| 讀取餘額、消費帳戶與 VAN | `LIST_PAYMENT`                    |
| 讀取交易分類帳        | `LIST_PAYMENT` + `LIST_PURCHASES` |
| 建立、編輯或關閉消費帳戶   | `MANAGE_PAYMENT`                  |
| 存入、轉帳或提領       | `MANAGE_PAYMENT`                  |

***

## 下一步去哪裡

<CardGroup cols={2}>
  <Card title="Spend Accounts" icon="wallet" href="/features/spend-accounts">
    建立、重新命名與關閉承載餘額的帳戶。
  </Card>

  <Card title="Virtual Account Numbers" icon="building-columns" href="/features/virtual-account-numbers">
    直接將 RTP、FedNow、電匯與 ACH 入帳至消費帳戶。
  </Card>

  <Card title="Deposit Funds" icon="arrow-down-to-line" href="/features/deposit-from-external-accounts">
    從已連結的銀行帳戶或卡片拉入資金。
  </Card>

  <Card title="Withdraw Funds" icon="arrow-up-from-line" href="/features/withdraw-funds">
    將資金轉出至外部帳戶。
  </Card>

  <Card title="Transfer Between Accounts" icon="right-left" href="/features/transfer-between-spend-accounts">
    在使用者自己的消費帳戶之間移動餘額。
  </Card>

  <Card title="Get All Transactions" icon="list" href="/features/get-all-transactions">
    完整的分類帳，含篩選與分頁。
  </Card>
</CardGroup>

***

**想了解更多？** 與我們的專家聯繫以取得更多資訊或申請示範。