> ## 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.
# Wallets & Transfers
> How money is held and moved on Fluz — balance types, spend accounts, funding in from external sources or virtual account numbers, and reading the ledger.
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
```mermaid theme={null}
flowchart LR
subgraph IN["Money In"]
F1["Bank account (ACH)"]
F2["Bank card"]
F3["PayPal / Apple Pay"]
F4["Virtual account number\nRTP · FedNow · Wire · ACH"]
F5["Fluz gift card redemption"]
F6["Cashback earned"]
end
subgraph BAL["Balances"]
SA1["Spend Account\n'Operations'"]
SA2["Spend Account\n'Team Travel'"]
RW["Rewards Balance"]
GC["Gift Card Balance\nnon-withdrawable"]
RS["Reserve Balance\nnon-withdrawable"]
end
subgraph OUT["Money Out"]
O1["Gift card purchases"]
O2["Virtual card funding"]
O3["Transfers to other\nFluz accounts"]
O4["Withdrawals to\nexternal accounts"]
end
F1 & F2 & F3 --> SA1
F4 --> SA1
F4 --> SA2
F5 --> GC
F6 --> RW
SA1 & SA2 --> O1 & O2 & O3 & O4
RW --> O1 & O4
GC --> O1 & O2
RS -.->|covers failed settlement| O1
```
***
## 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](/features/spend-accounts) — `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](/features/transfer-between-spend-accounts).
```mermaid theme={null}
flowchart TD
ACC["Fluz Account"]
ACC --> RW["Rewards Balance\naccount-level, one only"]
ACC --> GC["Gift Card Balance\naccount-level, one only"]
ACC --> RS["Reserve Balance\naccount-level, one only"]
ACC --> SAS["Spend Accounts\none or many"]
SAS --> S1["'Operations'\ntotal · available · lifetime\n+ virtual account numbers"]
SAS --> S2["'Team Travel'\ntotal · available · lifetime\n+ virtual account numbers"]
SAS --> S3["'Marketing'\ntotal · available · lifetime\n+ virtual account numbers"]
S1 <-->|internal transfer| S2
S2 <-->|internal transfer| S3
```
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.
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.
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](/features/deposit-from-external-accounts) | ACH pull, card, PayPal | Your app | A chosen spend account |
| [Virtual account number](/features/virtual-account-numbers) | RTP, FedNow, Wire, ACH credit | An external sender | The spend account behind that VAN |
| [Redeem a Fluz gift card](/features/redeem-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](/features/virtual-account-numbers).
***
## Moving and Removing Funds
| Action | Operation | Scope |
| ---------------------------------------------------------------------------- | ----------------------- | ---------------- |
| [Transfer between spend accounts](/features/transfer-between-spend-accounts) | Internal transfer | `MANAGE_PAYMENT` |
| [Transfer to another Fluz account](/features/application-transfer) | Wallet transfer | `MANAGE_PAYMENT` |
| [Look up a transfer recipient](/features/lookup-recipient) | Resolve an `account_id` | — |
| [Withdraw to an external account](/features/withdraw-funds) | 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.
```graphql theme={null}
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`](/features/get-spend-accounts).
**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`
```graphql theme={null}
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
}
}
```
```json Variables theme={null}
{
"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](/features/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
Create, rename, and close the accounts that hold the balance.
Receive RTP, FedNow, wire, and ACH credits directly into a spend account.
Pull money in from a linked bank account or card.
Move money out to an external account.
Move balance between a user's own spend accounts.
The full ledger, with filtering and pagination.
***
**Want to learn more?** Speak with our experts for more info or to request a demo.