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

# 關閉消費帳戶

# 概述

每個現金餘額帳戶都可以關閉，所有餘額會被轉移，且相依的虛擬卡之資金來源會被更改，或是虛擬卡會被鎖定。

# 關閉使用者現金餘額帳戶

## 範例請求

你可以使用 `closeUserCashBalance` mutation 關閉使用者現金餘額帳戶。此 mutation 可讓你執行以下操作：

* 關閉你的消費帳戶。
* 若有任何以此消費帳戶作為資金來源的虛擬卡，變更其資金來源。
* 鎖定相關的虛擬卡。
* 將剩餘餘額轉移至另一個消費帳戶。

此查詢接受 `CloseUserCashBalanceInput` 輸入物件。

```graphql theme={null}
mutation closeUserCashBalance($input: CloseUserCashBalanceInput!) {
    closeUserCashBalance(input: $input) {
        closedUserCashBalance {
            userCashBalanceId
            lifetimeCashBalance
            nickname
            status
            createdAt
            closedAt
        }
        affectedVirtualCards {
            virtualCardId
            virtualCardLast4
        }
    }
}
```

此 mutation 需要 `CloseUserCashBalanceInput` 輸入型別。任何在結構定義中以驚嘆號（`!`）標記的欄位皆為必填，必須包含於請求中。

## CloseUserCashBalanceInput

| 欄位名稱                      | 型別                                | 說明                                                           |
| :------------------------ | :-------------------------------- | :----------------------------------------------------------- |
| idempotencyKey            | UUID!                             | 由用戶端產生的唯一 UUID，確保請求只會被處理一次。                                  |
| userCashBalanceId         | UUID!                             | 現金餘額帳戶的唯一識別碼。                                                |
| newFundingSource          | CloseUserCashBalanceFundingSource | 所有相依虛擬卡的新資金來源。僅在有虛擬卡綁定此現金餘額帳戶且未提供 `lockAllVirtualCards` 時必填。 |
| lockAllVirtualCards       | Boolean                           | 是否鎖定所有相依的虛擬卡。僅在有虛擬卡綁定此現金餘額帳戶且未提供 `newFundingSource` 時必填。     |
| transferUserCashBalanceId | UUID                              | 轉移的唯一識別碼。僅在現金餘額帳戶的可用餘額大於 0 時必填。                              |

### 範例

```json theme={null}
{
  "idempotencyKey": "65666780-c552-47f0-ba05-f90fced0ef9f",
  "userCashBalanceId": "ca8e1ccf-b42d-41d3-8cad-2237e020d1b1",
  "lockAllVirtualCards": true,
  "transferUserCashBalanceId": "6d1b4b19-deef-42f5-80d7-ec34804ce091"
}
```

## CloseUserCashBalanceFundingSource

| 欄位名稱                           | 型別                       | 說明                         |
| :----------------------------- | :----------------------- | :------------------------- |
| bankAccountId                  | UUID                     | 銀行帳戶的唯一識別碼。若未提供其他選項則為必填。   |
| userCashBalanceId              | UUID                     | 現金餘額帳戶的唯一識別碼。若未提供其他選項則為必填。 |
| primaryFundingSource:          | VirtualCardFundingSource | 主要資金來源的型別，`FLUZ_BALANCE`   |
| 或 `BANK_ACCOUNT`。若未提供其他選項則為必填。 |                          |                            |

### 範例

```json theme={null}
{
  "userCashBalanceId": "ca8e1ccf-b42d-41d3-8cad-2237e020d1b1",
}
```

## 範例回應

`closeUserCashBalance` mutation 的回應會包含已關閉的現金餘額帳戶詳細資訊，包括其唯一識別碼與受影響的虛擬卡清單。

```json theme={null}
{
    "data": {
        "closeUserCashBalance": {
            "closedUserCashBalance": {
                "userCashBalanceId": "ca8e1ccf-b42d-41d3-8cad-2237e020d1b1",
                "lifetimeCashBalance": "0.00000",
                "nickname": "Closed Spend Account",
                "status": "CLOSED",
                "createdAt": "2025-12-30T21:18:26.782Z",
                "closedAt": "2025-12-30T21:22:29.359Z"
            },
            "affectedVirtualCards": [
                {
                    "virtualCardId": "afad4d6d-11f0-4ac1-b971-caca7c34c77c",
                    "virtualCardLast4": "4473"
                }
            ]
        }
    }
}
```

### 回應欄位

| 欄位名稱                 | 型別                                         | 說明               |
| :------------------- | :----------------------------------------- | :--------------- |
| closeUserCashBalance | ClosedUserCashBalance!                     | 已關閉之現金餘額帳戶的詳細資訊。 |
| lifetimeCashBalance  | \[CloseUserCashBalanceResponseVirtualCard] | 受關閉影響之虛擬卡的清單。    |

#### closeUserCashBalance

| 欄位名稱                | 型別                     | 說明                     |
| :------------------ | :--------------------- | :--------------------- |
| userCashBalanceId   | UUID!                  | 現金餘額帳戶的唯一識別碼。          |
| lifetimeCashBalance | String!                | 曾經存入之所有資金的累計總額（起始為 0）。 |
| nickname            | String!                | 指派給帳戶的自訂名稱。            |
| status              | UserCashBalanceStatus! | 帳戶目前狀態（應為 `CLOSED`）。   |
| createdAt           | DateTime!              | 帳戶建立的時間戳。              |
| closedAt            | DateTime!              | 帳戶關閉的時間戳。              |

#### affectedVirtualCards

| 欄位名稱             | 型別    | 說明         |
| :--------------- | :---- | :--------- |
| virtualCardId    | UUID! | 虛擬卡的唯一識別碼。 |
| virtualCardLast4 | UUID! | 虛擬卡卡號的後四碼。 |

<br />

> ❗️ 需要授權
>
> 此 mutation 需要 `MANAGE_PAYMENT` 權限範圍。在嘗試建立現金餘額帳戶之前，請確保你的存取權杖已被授與此範圍。