概觀

使用者現金餘額帳戶是一種消費帳戶，讓使用者能在 Fluz 平台上管理與追蹤其可用資金。每個現金餘額帳戶都有唯一的暱稱，並分別維護「總餘額」、「可用餘額」與「累積存入」等獨立數值。使用者可以建立多個現金餘額帳戶（例如「Team Travel」、「Operations Wallet」、「Marketing Budget」），以便依不同用途組織支出。在 Fluz 平台上進行存款、購買禮品卡，以及為虛擬卡交易提供資金，均需要現金餘額帳戶。

建立使用者現金餘額帳戶

範例請求

你可以使用 createUserCashBalance mutation 來建立新的使用者現金餘額帳戶。此 mutation 允許你設定自訂暱稱的新消費帳戶，以協助整理資金。該查詢接受一個 CreateUserCashBalanceInput 輸入物件。

{
  "query": "mutation createUserCashBalance($input: CreateUserCashBalanceInput!) { createUserCashBalance(input: $input) { userCashBalanceId totalCashBalance availableCashBalance lifetimeCashBalance nickname status createdAt }}",
  "variables": {
    "input": {
      "nickname": "Team Travel"
    }
  }
}

此 mutation 需要 CreateUserCashBalanceInput 輸入型別。任何在結構描述（schema）中以驚嘆號（!）標註的欄位皆為必填，必須包含於請求中。

欄位名稱	型別	說明
nickname	String!	現金餘額帳戶的自訂名稱，有助於辨識帳戶用途。

CreateUserCashBalanceInput

{
  "nickname": "Team Travel"
}

範例回應

createUserCashBalance mutation 的回應會包含新建立的現金餘額帳戶詳細資訊，包括其唯一識別碼與初始餘額資訊。

{
  "data": {
    "createUserCashBalance": {
      "userCashBalanceId": "f8a3c9e1-7b2d-4f5e-9c8a-1d2e3f4g5h6i",
      "totalCashBalance": "0",
      "availableCashBalance": "0",
      "lifetimeCashBalance": "0",
      "nickname": "Team Travel",
      "status": "ACTIVE",
      "createdAt": "2025-01-15T10:30:00.000Z"
    }
  }
}

回應欄位

欄位名稱	型別	說明
userCashBalanceId	UUID!	現金餘額帳戶的唯一識別碼
totalCashBalance	String!	帳戶中的總現金餘額（起始為 0）
availableCashBalance	String!	可立即使用的現金餘額（起始為 0）
lifetimeCashBalance	String!	有史以來所有存入資金的累計總額（起始為 0）
nickname	String	指派給帳戶的自訂名稱
status	UserCashBalanceStatus!	帳戶目前狀態（ACTIVE、CLOSED 或 SUSPENDED）
createdAt	DateTime!	建立帳戶的時間戳記

❗️ 需要授權此 mutation 需要 MANAGE_PAYMENT 權限範圍。在嘗試建立現金餘額帳戶之前，請確保你的 access token 已被授予此範圍。

功能

建立消費帳戶

概觀

建立使用者現金餘額帳戶

範例請求

CreateUserCashBalanceInput

範例回應

回應欄位

​概觀

​建立使用者現金餘額帳戶

​範例請求

​CreateUserCashBalanceInput

​範例回應

​回應欄位

概觀

建立使用者現金餘額帳戶

範例請求

CreateUserCashBalanceInput

範例回應

回應欄位