Overview

Each cash balance account can be closed, with all it's balance transferred and depending virtual cards' funding source changed or them being locked.

Close User Cash Balance Account

Sample request

You can close a user cash balance account with the closeUserCashBalance mutation. This mutation allows you to do the following:

Close your spending account.
Change virtual cards funding source if there are any that have this spending account as one.
Lock related virtual cards.
Transfer the remaining balance to another spend account.

The query takes a CloseUserCashBalanceInput input object.

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

This mutation requires the CloseUserCashBalanceInput input type. Any field marked with an exclamation mark (!) in the schema is mandatory and must be included in the request.

CloseUserCashBalanceInput

Field name	Type	Description
idempotencyKey	UUID!	A unique client-generated UUID to ensure a request is processed only once.
userCashBalanceId	UUID!	An unique identifier for the cash balance account.
newFundingSource	CloseUserCashBalanceFundingSource	A new funding source for all dependent virtual cards. Required only if there are virtual cards tied to this cash balance account and `lockAllVirtualCards` is not provided.
lockAllVirtualCards	Boolean	Whether to lock all dependent virtual cards. Required only if there are virtual cards tied to this cash balance account and `newFundingSource` is not provided.
transferUserCashBalanceId	UUID	An unique identifier for the transfer. Required only if cash balance account's available balance is >0.

Example

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

CloseUserCashBalanceFundingSource

Field name	Type	Description
bankAccountId	UUID	An unique identifier for the bank account. Required if other options aren't present.
userCashBalanceId	UUID	An unique identifier for the cash balance account. Required if other options aren't present.
primaryFundingSource:	VirtualCardFundingSource	A type of a primary funding source, either `FLUZ_BALANCE`
or `BANK_ACCOUNT`. Required if other options aren't present.

Example

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

Sample response

The response from the closeUserCashBalance mutation will include a closed cash balance account details, including its unique identifier and a list of affected virtual cards.

{
    "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"
                }
            ]
        }
    }
}

Response Fields

Field name	Type	Description
closeUserCashBalance	ClosedUserCashBalance!	Closed cash balance account details.
lifetimeCashBalance	[CloseUserCashBalanceResponseVirtualCard]	A list of virtual cards affected by the closure.

closeUserCashBalance

Field name	Type	Description
userCashBalanceId	UUID!	Unique identifier for the cash balance account.
lifetimeCashBalance	String!	Cumulative total of all funds ever deposited (starts at 0).
nickname	String!	The custom name assigned to the account.
status	UserCashBalanceStatus!	Current status of the account (should be `CLOSED`).
createdAt	DateTime!	Timestamp when the account was created.
closedAt	DateTime!	Timestamp when the account was closed.

affectedVirtualCards

Field name	Type	Description
virtualCardId	UUID!	Unique identifier for the virtual card.
virtualCardLast4	UUID!	The last four digits of the virtual card number.

❗️
Authorization required
This mutation requires the MANAGE_PAYMENT scope. Ensure your access token has been granted this scope before attempting to create a cash balance account.