概述

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

關閉使用者現金餘額帳戶

範例請求

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

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

此查詢接受 CloseUserCashBalanceInput 輸入物件。

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 時必填。

範例

{
  "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`。若未提供其他選項則為必填。

範例

{
  "userCashBalanceId": "ca8e1ccf-b42d-41d3-8cad-2237e020d1b1",
}

範例回應

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

{
    "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!	虛擬卡卡號的後四碼。

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

功能

關閉消費帳戶

概述

關閉使用者現金餘額帳戶

範例請求

CloseUserCashBalanceInput

範例

CloseUserCashBalanceFundingSource

範例

範例回應

回應欄位

closeUserCashBalance

affectedVirtualCards

​概述

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

​範例請求

​CloseUserCashBalanceInput

​範例

​CloseUserCashBalanceFundingSource

​範例

​範例回應

​回應欄位

​closeUserCashBalance

​affectedVirtualCards

概述

關閉使用者現金餘額帳戶

範例請求

CloseUserCashBalanceInput

範例

CloseUserCashBalanceFundingSource

範例

範例回應

回應欄位

closeUserCashBalance

affectedVirtualCards