Wallets & Transfers

Every dollar on Fluz sits in a balance. Money enters a balance from an external funding source or a virtual account number, moves between balances through transfers, and leaves through purchases or withdrawals. This section covers all of it. The most useful thing to understand first: an account does not have one balance. It has several, and they behave differently. Some are withdrawable, some are not, and one of them — the spend account — can exist many times over.

The Money Map

Balance Types

An account can hold up to four kinds of balance. Spend accounts are the only kind a user can have more than one of.

Balance	Withdrawable	What it holds
Spend account (cash balance)	Yes	The main working balance. Funds gift cards, virtual cards, transfers, and withdrawals.
Rewards balance	Yes	Cashback and bonus rewards earned on Fluz activity.
Gift card balance	No	Prepaid value usable toward gift card and virtual card purchases only.
Reserve balance	No	Held by Fluz to cover transactions that fail to settle, keeping the account in good standing.

The sum of these is the account’s available Fluz balance — the total that can be applied toward funding a payment.

The same balance appears under more than one name.The gift card balance is returned as giftCardCashBalance on getWallet and as gift_card_prepayment_balance_* on the Transaction type. The rewards balance is rewardsBalance on getWallet and seat_balance_* on Transaction. These are aliases, not separate pots of money.

Spend Accounts Hold the Balance

A spend account — UserCashBalance in the API — is a named container for cash. A user can open several and give each one a nickname, so funds can be separated by purpose without opening separate Fluz accounts. Each spend account carries its own independent balance. Money in one is not spendable from another until it is moved with an internal transfer. Every spend account tracks three figures, all returned as strings:

Field	Meaning
`totalCashBalance`	The full balance currently held in the account.
`availableCashBalance`	The portion that can be spent right now.
`lifetimeCashBalance`	Cumulative total ever deposited into this account.

Getting Funds In

There are two fundamentally different directions money can move into a balance, and the distinction matters for how you build.

Pull — you initiate

Your application calls depositCashBalance and Fluz pulls funds from a funding source the user has already linked: a bank account, bank card, or digital wallet. You control the timing and the amount.

Push — someone else initiates

An outside party sends money to a virtual account number attached to a spend account. Fluz posts it as a deposit when it arrives. You do not control the timing or the amount.

Path	Rails	Initiated by	Lands in
Deposit funds	ACH pull, card, PayPal	Your app	A chosen spend account
Virtual account number	RTP, FedNow, Wire, ACH credit	An external sender	The spend account behind that VAN
Redeem a Fluz gift card	—	The user	Gift card balance
Cashback on qualifying activity	—	Fluz	Rewards balance

A virtual account number is an address, not a balance.Each spend account can have one or more virtual account numbers — real routing and account number pairs. Anything sent to them credits that spend account. Multiple VANs on one account all feed the same balance; they exist so you can tell a payroll credit apart from a customer payment. See Virtual Account Numbers.

Moving and Removing Funds

Action	Operation	Scope
Transfer between spend accounts	Internal transfer	`MANAGE_PAYMENT`
Transfer to another Fluz account	Wallet transfer	`MANAGE_PAYMENT`
Look up a transfer recipient	Resolve an `account_id`	—
Withdraw to an external account	Withdrawal	`MANAGE_PAYMENT`

The gift card and reserve balances cannot be withdrawn. Gift card balance can only be spent on gift card and virtual card purchases. Reserve balance is held by Fluz and is not user-directed.

Reading Balances

getWallet returns the account’s balances in one call, alongside the user’s linked funding sources.

query getWallet {
  getWallet {
    balances {
      rewardsBalance      { availableBalance totalBalance lifetimeBalance }
      cashBalance         { availableBalance totalBalance pendingBalance lifetimeBalance }
      giftCardCashBalance { availableBalance totalBalance pendingBalance lifetimeBalance }

      userCashBalances(paginate: { limit: 10, offset: 0 }) {
        userCashBalanceId
        nickname
        totalCashBalance
        availableCashBalance
        lifetimeCashBalance
        status
        createdAt
      }
    }
    blockedPaymentTypes
  }
}

userCashBalances is paginated and returns accounts ordered by creation date, most recent first. To fetch a single spend account, use getUserCashBalanceById.

To show a user’s total spendable cash, sum availableCashBalance across userCashBalances. Do not add cashBalance on top of the individual spend account figures — doing so will overstate the total.

The reserve balance is held by Fluz rather than directed by the user. Its current state is visible on each transaction through the reserve_balance_available_balance and reserve_balance_total_balance snapshot fields described below.

Reading the Ledger

Balances tell you where things stand. getTransactions tells you how they got there. To see the ledger for one specific spend account, filter by its ID. Scopes required: LIST_PAYMENT and LIST_PURCHASES

query spendAccountLedger($userCashBalanceId: [UUID], $limit: Int, $offset: Int) {
  getTransactions(
    filter: { userCashBalanceId: $userCashBalanceId }
    paginate: { limit: $limit, offset: $offset }
  ) {
    transactions {
      record_id
      transaction_type
      amount
      source
      destination
      status
      used_user_cash_balance_id
      cash_balance_available_balance
      created_at
    }
    totalCount
    hasNextPage
  }
}

Variables

{
  "userCashBalanceId": ["9c1f6b2e-4d7a-4c3b-9f11-2a5e8b0d6c74"],
  "limit": 20,
  "offset": 0
}

Every transaction also carries a balance snapshot — the state of each balance after that transaction was applied — plus flags indicating which balances the transaction touched:

Balance	Snapshot fields	Affected flag
Spend / cash	`cash_balance_available_balance` · `cash_balance_total_balance`	`is_cash_balance_affected`
Rewards	`seat_balance_available_balance` · `seat_balance_total_balance`	`is_seat_balance_affected`
Gift card	`gift_card_prepayment_balance_available_balance` · `gift_card_prepayment_balance_total_balance`	`is_gift_card_balance_affected`
Reserve	`reserve_balance_available_balance` · `reserve_balance_total_balance`	`is_reserve_balance_affected`
Other cash	`other_cash_balance_available_balance` · `other_cash_balance_total_balance`	—

Only spend accounts can be filtered by ID. TransactionFilterInput exposes userCashBalanceId, but there is no equivalent filter for the rewards, gift card, or reserve balances. To isolate activity on those, retrieve transactions over a date range and filter on the corresponding is_..._affected flag.

getTransactions is capped at 20 records per page. Check hasNextPage and advance offset to page through. See Get All Transactions for the complete filter reference.

Scopes at a Glance

You want to…	Scope
Read balances, spend accounts, and VANs	`LIST_PAYMENT`
Read the transaction ledger	`LIST_PAYMENT` + `LIST_PURCHASES`
Create, edit, or close a spend account	`MANAGE_PAYMENT`
Deposit, transfer, or withdraw	`MANAGE_PAYMENT`

Where to Go Next

Spend Accounts

Create, rename, and close the accounts that hold the balance.

Virtual Account Numbers

Receive RTP, FedNow, wire, and ACH credits directly into a spend account.

Deposit Funds

Pull money in from a linked bank account or card.

Withdraw Funds

Move money out to an external account.

Transfer Between Accounts

Move balance between a user’s own spend accounts.

Get All Transactions

The full ledger, with filtering and pagination.

Want to learn more? Speak with our experts for more info or to request a demo.

​The Money Map

​Balance Types

​Spend Accounts Hold the Balance

​Getting Funds In

Pull — you initiate

Push — someone else initiates

​Moving and Removing Funds

​Reading Balances

​Reading the Ledger

​Scopes at a Glance

​Where to Go Next

Spend Accounts

Virtual Account Numbers

Deposit Funds

Withdraw Funds

Transfer Between Accounts

Get All Transactions

The Money Map

Balance Types

Spend Accounts Hold the Balance

Getting Funds In

Moving and Removing Funds

Reading Balances

Reading the Ledger

Scopes at a Glance

Where to Go Next