- 這筆錢在哪個餘額中？ 每個餘額規則不同——有些可提領，有些只能消費。
- 在現金餘額中的哪個消費帳戶？ 現金被分割成具名的次分類帳。選錯帳戶是最常見的失敗原因。
- 資金是往內、在內部移動，還是往外？ 每個方向都是不同的變更，範圍也不同。
四種餘額
Cash balance
工作用的餘額。由存款補充，花費於禮品卡與虛擬卡，可提領到外部帳戶。它不是單一池子——而是你的消費帳戶的總和，下一節將介紹。Rewards balance
購買所賺取的現金回饋。可完全提領且可完全消費。不同於現金與預付餘額，它不帶有待入帳金額，因為回饋在賺取時即入帳，而不是隨時間結算。 要從該餘額提領，請傳入source: "REWARDS_BALANCE"——除了現金餘額外，withdrawCashBalance 唯一接受的餘額。
Prepayment balance
一種餘額，四個名稱。 在產品層面稱為 prepayment balance（預付餘額）。API 欄位是
giftCardCashBalance，存款列舉值是 GIFT_CARD_BALANCE，且有些頁面仍稱為「gift card balance」。都是同一件事。depositType: "GIFT_CARD_BALANCE" 的存款，或兌換 Fluz Gift Card 代碼——也可以用於消費，但它永遠不能提領到外部帳戶。 進入預付餘額的資金只能透過消費離開。
這是設計重點，而非限制：它是預付價值，因此將其存入視為一種承諾。如果你可能需要將資金轉回，請改存入現金餘額。
Reserve balance
透過depositType: "RESERVE_BALANCE" 存入，並加以保留。不允許提領。
Spend accounts
消費帳戶是現金餘額底下的具名次分類帳——例如「Operations」、「Team Travel」、「Client A」——同屬一個 Fluz 帳戶之下，各自擁有其餘額。「Spend account」、「cash balance」與
UserCashBalance 指的是相同物件。 產品層面呈現為消費帳戶；API 型別是 UserCashBalance，因此欄位為 userCashBalanceId、availableCashBalance 等。請不要與 bankAccountId 混淆，後者指的是「外部」已連結的銀行帳戶。isDefault 的那一個。
三個數字
每個消費帳戶追蹤三個金額，它們回答不同的問題：
在任何大量操作前先檢查
availableCashBalance。totalCashBalance 減去 available 即為在途中流動的金額。
管理它們
→ 消費帳戶 · 取得消費帳戶
資金移動的所有方式
轉入 — 從外部來源存入
depositCashBalance 從已連結的資金來源提取資金，存入你選擇的餘額。
- 資金來源：
bankAccountId、bankCardId或paypalVaultId，皆可從getWallet取得。 - 目的地：
depositType可為CASH_BALANCE、GIFT_CARD_BALANCE或RESERVE_BALANCE。 - 消費帳戶： 使用
CASH_BALANCE時，請以userCashBalanceId明確指定目標帳戶。
balances 物件反映可即時使用的金額，因此請讀取它，而不要假設全額已入帳。
→ 從外部帳戶存入資金 · 資金來源
轉入 — 兌換 Fluz Gift Card
redeemFluzGiftCard 將 Fluz Gift Card 的代碼直接入帳至預付餘額。兌換是即時的，任何啟用費將回傳在 depositFee。
這是唯一一種在沒有連結資金來源的情況下，將價值存入錢包的方法——適用於促銷、回扣與贈禮，受贈者可能完全沒有連結任何銀行帳戶。
→ 兌換 Fluz Gift Card
內部移轉 — 在你自己的消費帳戶之間
transferInternalBalance 在你擁有的兩個消費帳戶之間移動資金。內部會被記錄為兩個關聯動作——來源帳戶的提領與目的帳戶的存入——回應會同時回傳兩者。
內部移轉 — 轉給另一個 Fluz 使用者
轉給「不同」的 Fluz 帳戶是另一個操作。可用accountId 指定目的地，或用你自己的識別碼 externalReferenceId——請見管理 External Reference ID。收款方必須已授權你的應用程式。
→ 帳戶對帳戶轉帳 · 收款方查找
轉出 — 提領至外部帳戶
withdrawCashBalance 將資金轉出。選擇來源餘額——CASH_BALANCE 或 REWARDS_BALANCE，這兩者是唯一支援提領的餘額——與方法，並提供相對應的目的地 ID：
當來源是現金餘額時，請指定要扣款的消費帳戶。ACH 通常先呈現
PENDING 或 PROCESSING 狀態，而非立即完成。
提領的輸入欄位將消費帳戶命名為
cashBalanceId，而存款與購買則使用 userCashBalanceId。同一個物件，不同的欄位名稱——已知的不一致，請留意。讀取餘額
兩個查詢、兩種粒度：getWallet 也是你取得每次存入與提領所需資金來源 ID 的地方。移動資金前先檢查餘額，而不是等到失敗再處理。
→ 檢查帳戶餘額 · 檢視資金來源
冪等性
每個資金移動的變更——存款、兌換、內部移轉、帳戶對帳戶轉帳、提領——都需要一個唯一且由用戶端產生的idempotencyKey。
以相同 key 重送請求會回傳原結果，而不會再次處理。為每一次預期的資金移動產生一個 key，並在該次移動的每次重試都重用它。 為重試產生新 key 會導致重複轉帳。
→ 冪等性
Scopes
請先在你應用程式的「Permissions」分頁啟用這些範圍——若你請求了未啟用的 scope，系統會靜默忽略而非拒絕。→ 設定 OAuth App
下一步
透過錢包移動資金
從頭到尾的完整生命週期，可直接執行的快速上手。
消費帳戶
建立、資金補充、重新命名與關閉次分類帳。
資金來源
連結銀行卡、銀行帳戶與數位錢包。
存入資金
完整的存款輸入參考。
提領資金
方法、時間與錯誤處理。
交易活動
將所有移動匯整於一個可篩選的資訊流。