> ## 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 平台上管理與追蹤其可用資金。每個現金餘額帳戶都有唯一的暱稱，並分別維護「總餘額」、「可用餘額」與「累積存入」等獨立數值。使用者可以建立多個現金餘額帳戶（例如「Team Travel」、「Operations Wallet」、「Marketing Budget」），以便依不同用途組織支出。

在 Fluz 平台上進行存款、購買禮品卡，以及為虛擬卡交易提供資金，均需要現金餘額帳戶。

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

## 範例請求

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

```json theme={null}
{
  "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

```json theme={null}
{
  "nickname": "Team Travel"
}
```

## 範例回應

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

```json theme={null}
{
  "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 已被授予此範圍。

<StickyContactSalesBanner />