錢包與轉帳 - Fluz

在 Fluz 上的每一美元都放在一個餘額中。資金可從外部資金來源或虛擬帳號進入某個餘額，透過轉帳在不同餘額之間移動，並透過購買或提領離開。本節將完整說明。首先最重要的觀念：一個帳戶不只擁有一個餘額。它有多個，且行為各不相同。 有些可提領、有些不可，而其中之一——消費帳戶——可以同時存在多個。

資金地圖

餘額類型

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

Balance	Withdrawable	What it holds
Spend account (cash balance)	Yes	主要的作業餘額。可用於禮品卡、虛擬卡、轉帳與提領。
Rewards balance	Yes	在 Fluz 活動中獲得的現金回饋與獎勵。
Gift card balance	No	僅可用於購買禮品卡與虛擬卡的預付金額。
Reserve balance	No	由 Fluz 持有，用於承擔結算失敗的交易，維持帳戶良好狀態。

這些合計為帳戶的可用 Fluz 餘額——可用於支付資金的總額。

同一個餘額可能以多個名稱出現。禮品卡餘額在 getWallet 中回傳為 giftCardCashBalance，而在 Transaction 類型上則為 gift_card_prepayment_balance_*。回饋餘額在 getWallet 中為 rewardsBalance，而在 Transaction 上為 seat_balance_*。這些只是別名，並非不同的資金池。

消費帳戶承載餘額

消費帳戶——在 API 中為 UserCashBalance——是現金的具名容器。使用者可開立多個並為每個取暱稱，讓資金可依用途分隔，而不需開立獨立的 Fluz 帳戶。 每個消費帳戶都有其獨立的餘額。 在將資金透過內部轉帳移動之前，一個帳戶中的資金無法自另一個帳戶動用。每個消費帳戶會追蹤三個數值，皆以字串回傳：

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

入金方式

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

拉取（由你發起）

你的應用程式呼叫 depositCashBalance，Fluz 從使用者已連結的資金來源拉取資金：銀行帳戶、銀行卡或行動錢包。你可控管時間與金額。

推送（由他方發起）

外部方將資金匯入連結於消費帳戶的虛擬帳號。資金抵達時，Fluz 會入帳為存款。你無法控制時間與金額。

Path	Rails	Initiated by	Lands in
Deposit funds	ACH pull, card, PayPal	Your app	指定的消費帳戶
Virtual account number	RTP, FedNow, Wire, ACH credit	外部匯入者	該 VAN 背後的消費帳戶
Redeem a Fluz gift card	—	使用者	禮品卡餘額
Cashback on qualifying activity	—	Fluz	回饋餘額

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

移動與移除資金

Action	Operation	Scope
Transfer between spend accounts	Internal transfer	`MANAGE_PAYMENT`
Transfer to another Fluz account	Wallet transfer	`MANAGE_PAYMENT`
Look up a transfer recipient	Resolve an `account_id`	—
Withdraw to an external account	Withdrawal	`MANAGE_PAYMENT`

禮品卡與保留餘額不可提領。 禮品卡餘額僅能用於購買禮品卡與虛擬卡。保留餘額由 Fluz 持有，並非由使用者自行支配。

讀取餘額

getWallet 會在一次呼叫中回傳帳戶的各項餘額，並附帶使用者已連結的資金來源。

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。

若要顯示使用者的可支用現金總額，請對 userCashBalances 中的 availableCashBalance 加總。 請勿再將 cashBalance 疊加至各個消費帳戶數值之上——這會高估總額。

保留餘額由 Fluz 持有而非使用者直接操作。其當前狀態可於每筆交易上透過 reserve_balance_available_balance 與 reserve_balance_total_balance 的快照欄位查看，說明如下。

閱讀分類帳

餘額告訴你當下狀態；getTransactions 告訴你如何到達該狀態。若要查看特定消費帳戶的分類帳，請依其 ID 篩選。 所需範圍（Scopes）： LIST_PAYMENT 以及 LIST_PURCHASES

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
  }
}

Variables

{
  "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`	—

只有消費帳戶可用 ID 篩選。 TransactionFilterInput 提供 userCashBalanceId，但沒有對應於回饋、禮品卡或保留餘額的篩選器。若要聚焦於那些餘額的活動，請依日期範圍擷取交易，並據以篩選對應的 is_..._affected 旗標。

getTransactions 每頁最多回傳 20 筆。請檢查 hasNextPage 並遞增 offset 以翻頁。完整的篩選參照請見 Get All Transactions。

權限範圍一覽

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

下一步去哪裡

Spend Accounts

建立、重新命名與關閉承載餘額的帳戶。

Virtual Account Numbers

直接將 RTP、FedNow、電匯與 ACH 入帳至消費帳戶。

Deposit Funds

從已連結的銀行帳戶或卡片拉入資金。

Withdraw Funds

將資金轉出至外部帳戶。

Transfer Between Accounts

在使用者自己的消費帳戶之間移動餘額。

Get All Transactions

完整的分類帳，含篩選與分頁。

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

​資金地圖

​餘額類型

​消費帳戶承載餘額

​入金方式

拉取（由你發起）

推送（由他方發起）

​移動與移除資金

​讀取餘額

​閱讀分類帳

​權限範圍一覽

​下一步去哪裡

Spend Accounts

Virtual Account Numbers

Deposit Funds

Withdraw Funds

Transfer Between Accounts

Get All Transactions

資金地圖

餘額類型

消費帳戶承載餘額

入金方式

移動與移除資金

讀取餘額

閱讀分類帳

權限範圍一覽

下一步去哪裡