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

# Overview

> The four Fluz balances, how spend accounts partition the cash balance, and every way money moves in, around, and out.

A Fluz wallet is two things: a set of **balances** that hold value, and a set of **links to external accounts** that move value in and out. Every card, purchase, and payout in the rest of the API ultimately draws on this.

Three questions decide almost everything you'll build here:

* **Which balance is the money in?** They have different rules — some can be withdrawn, some can only be spent.
* **Which spend account inside the cash balance?** Cash is partitioned into named sub-ledgers, and picking the wrong one is the most common source of surprise failures.
* **Is the money moving in, around, or out?** Each direction is a different mutation with a different scope.

***

## The four balances

| Balance                | Funded by                                                 | Spendable | Withdrawable | API field             |
| :--------------------- | :-------------------------------------------------------- | :-------: | :----------: | :-------------------- |
| **Cash balance**       | Deposits from external funding sources                    |     ✓     |       ✓      | `cashBalance`         |
| **Rewards balance**    | Cashback earned on purchases                              |     ✓     |       ✓      | `rewardsBalance`      |
| **Prepayment balance** | Deposits to `GIFT_CARD_BALANCE`, redeemed Fluz Gift Cards |     ✓     |       ✗      | `giftCardCashBalance` |
| **Reserve balance**    | Deposits to `RESERVE_BALANCE`                             |     —     |       ✗      | —                     |

### Cash balance

The working balance. Funded by deposits, spent on gift cards and virtual cards, withdrawable to an external account. It is not a single pot — it's the **aggregate of your spend accounts**, which is the next section.

### Rewards balance

Cashback earned on purchases. Fully withdrawable and fully spendable. Unlike the cash and prepayment balances it carries no pending amount, because rewards post once they're earned rather than settling over time.

Withdraw from it by passing `source: "REWARDS_BALANCE"` — the only balance besides cash that `withdrawCashBalance` accepts.

### Prepayment balance

<Note>
  **One balance, four names.** The product calls it the **prepayment balance**. The API field is `giftCardCashBalance`, the deposit enum is `GIFT_CARD_BALANCE`, and some pages still call it the "gift card balance." All the same thing.
</Note>

Spend-only. You can fund it two ways — a deposit with `depositType: "GIFT_CARD_BALANCE"`, or by redeeming a Fluz Gift Card code — and you can spend it on purchases, but **it can never be withdrawn to an external account.** Money that enters the prepayment balance leaves only by being spent.

That's the design point, not a limitation: it's prepaid value, so treat a deposit into it as a commitment. If you might need the funds back out, deposit to the cash balance instead.

### Reserve balance

Funded by depositing with `depositType: "RESERVE_BALANCE"`, and held in reserve. Not withdrawable.

***

## Spend accounts

A **spend account** is a named sub-ledger of the cash balance — "Operations," "Team Travel," "Client A" — each with its own balance, living under one Fluz account.

<Note>
  **"Spend account," "cash balance," and `UserCashBalance` are the same object.** The product surfaces it as a spend account; the API type is `UserCashBalance`, so the fields are `userCashBalanceId`, `availableCashBalance`, and so on.

  Don't confuse it with `bankAccountId`, which refers to an *external* linked bank account.
</Note>

Every account has a **default** spend account. Deposits, purchases, and card funding that don't name an account resolve to whichever one is flagged `isDefault`.

<Warning>
  **If you hold more than one spend account, name it explicitly on every operation.** Relying on the default is the single most common cause of unexpected insufficient-funds failures — a new deposit routed elsewhere, or a change to which account is flagged default, silently redirects where money comes from while your code stays identical.
</Warning>

### The three numbers

Each spend account tracks three amounts, and they answer different questions:

| Field                  | Question it answers                                                           |
| :--------------------- | :---------------------------------------------------------------------------- |
| `availableCashBalance` | What can I spend **right now**?                                               |
| `totalCashBalance`     | What's in the account, including amounts not yet available?                   |
| `lifetimeCashBalance`  | What has **ever** been deposited here? Only ever grows — it's the audit trail |

Check `availableCashBalance` before any high-volume run. `totalCashBalance` minus available is money in flight.

### Managing them

| Operation | Mutation                                               |
| :-------- | :----------------------------------------------------- |
| Create    | `createUserCashBalance` — takes a `nickname`           |
| List      | `getUserCashBalances` — filterable and paginated       |
| Read one  | `getUserCashBalanceById`                               |
| Rename    | [Edit Spend Accounts](/features/edit-spend-accounts)   |
| Close     | [Close Spend Accounts](/features/close-spend-accounts) |

→ [Spend Accounts](/features/spend-accounts) · [Get Spend Accounts](/features/get-spend-accounts)

***

## Every way money moves

| From                    | To                             | Mutation                                   | Scope                    |
| :---------------------- | :----------------------------- | :----------------------------------------- | :----------------------- |
| External funding source | Cash balance / spend account   | `depositCashBalance` — `CASH_BALANCE`      | `MAKE_DEPOSIT`           |
| External funding source | Prepayment balance             | `depositCashBalance` — `GIFT_CARD_BALANCE` | `MAKE_DEPOSIT`           |
| External funding source | Reserve balance                | `depositCashBalance` — `RESERVE_BALANCE`   | `MAKE_DEPOSIT`           |
| Fluz Gift Card code     | Prepayment balance             | `redeemFluzGiftCard`                       | `MAKE_DEPOSIT`           |
| Your spend account      | Another of your spend accounts | `transferInternalBalance`                  | `MAKE_INTERNAL_TRANSFER` |
| Your account            | Another Fluz user's account    | `createTransfer`                           | —                        |
| Cash or rewards balance | External account               | `withdrawCashBalance`                      | `MAKE_WITHDRAWAL`        |
| Purchases               | Rewards balance                | Earned automatically                       | —                        |

### In — depositing from external sources

`depositCashBalance` pulls from a linked funding source into a balance you choose.

* **Funding source:** `bankAccountId`, `bankCardId`, or `paypalVaultId`, all retrieved from `getWallet`.
* **Destination:** `depositType` of `CASH_BALANCE`, `GIFT_CARD_BALANCE`, or `RESERVE_BALANCE`.
* **Spend account:** with `CASH_BALANCE`, target one explicitly using `userCashBalanceId`.

Settlement runs from instant to 2–5 business days depending on the source. The returned `balances` object reflects what's available immediately, so read it rather than assuming the full amount landed.

→ [Deposit Funds From External Accounts](/features/deposit-from-external-accounts) · [Funding Sources](/features/funding-sources)

### In — redeeming a Fluz Gift Card

`redeemFluzGiftCard` credits a Fluz Gift Card **code** straight to the prepayment balance. Redemption is instant, and any activation fee comes back in `depositFee`.

This is the only way to get value into the wallet without a linked funding source — useful for promotions, rebates, and gifting, where the recipient may have no bank account linked at all.

→ [Redeem Fluz Gift Card](/features/redeem-fluz-gift-card)

### Around — between your own spend accounts

`transferInternalBalance` moves funds between two spend accounts you own. Internally it's recorded as two linked movements — a withdrawal from the source and a deposit into the destination — and the response returns both.

```json theme={null}
{
  "input": {
    "idempotencyKey": "1f1df3e7-5d43-4e3d-83de-31922d4aefb7",
    "amount": 25.00,
    "sourceUserCashBalanceId": "<SOURCE_ACCOUNT_ID>",
    "destinationUserCashBalanceId": "<DESTINATION_ACCOUNT_ID>"
  }
}
```

Both IDs must be your own accounts, they must differ, and the source needs sufficient **available** balance. Internal transfers settle immediately — which makes this the fastest way to unblock a purchase that's drawing on the wrong account.

→ [Transfer Between Spend Accounts](/features/transfer-between-spend-accounts)

### Around — to another Fluz user

Sending to a *different* Fluz account is a separate operation. Address the destination by `accountId`, or by your own identifier with `externalReferenceId` — see [Managing External Reference IDs](/managing-external-reference-ids). The recipient must have authorized your application.

→ [Account to Account Transfers](/features/account-to-account-transfers) · [Recipient Lookup](/features/lookup-recipient)

### Out — withdrawing to an external account

`withdrawCashBalance` sends money out. Choose a **source balance** — `CASH_BALANCE` or `REWARDS_BALANCE`, the only two that support withdrawal — and a **method**, supplying the matching destination ID:

| Method      | Required field   | Timing and cost                                       |
| :---------- | :--------------- | :---------------------------------------------------- |
| `BANK_ACH`  | `bankAccountId`  | 1–3 business days, no fees                            |
| `BANK_CARD` | `bankCardId`     | Push-to-card to an eligible debit card, may have fees |
| `PAYPAL`    | `paypalVaultId`  | May have fees                                         |
| `VENMO`     | `venmoAccountId` | May have fees                                         |

When the source is the cash balance, name the spend account to draw from. Expect an initial `PENDING` or `PROCESSING` status on ACH rather than immediate completion.

<Note>
  The withdraw input names the spend account field `cashBalanceId`, while deposits and purchases use `userCashBalanceId`. Same object, different field name — a known inconsistency worth watching for.
</Note>

→ [Withdraw to External Account](/features/withdraw-to-external-account)

***

## Reading balances

Two queries, two granularities:

| Query                 | Returns                                                                                                                       |
| :-------------------- | :---------------------------------------------------------------------------------------------------------------------------- |
| `getWallet`           | All balances — `cashBalance`, `rewardsBalance`, `giftCardCashBalance` — plus linked funding sources and `blockedPaymentTypes` |
| `getUserCashBalances` | Per-spend-account detail: nickname, `isDefault`, status, and the three amounts                                                |

`getWallet` is also where you get the funding source IDs every deposit and withdrawal needs. Check balances before moving money rather than reacting to a failure.

→ [Check Account Balance](/check-account-balance) · [View Funding Sources](/features/view-funding-sources)

***

## Idempotency

Every money-moving mutation — deposit, redemption, internal transfer, account-to-account transfer, withdrawal — requires a unique, client-generated `idempotencyKey`.

Resubmitting the same key returns the original result instead of processing again. **Generate one key per intended movement and reuse it on every retry of that movement.** A fresh key for a retry is how duplicate transfers happen.

→ [Idempotency](/concepts/idempotency)

***

## Scopes

| Scope                    | Covers                                                   |
| :----------------------- | :------------------------------------------------------- |
| `LIST_PAYMENT`           | Reading wallets, balances, and funding sources           |
| `MANAGE_PAYMENT`         | Creating and managing spend accounts and funding sources |
| `MAKE_DEPOSIT`           | Deposits and Fluz Gift Card redemption                   |
| `MAKE_INTERNAL_TRANSFER` | Moving funds between your own spend accounts             |
| `MAKE_WITHDRAWAL`        | Sending funds to external accounts                       |

Enable these on your app's **Permissions** tab first — a scope you request but haven't enabled is silently dropped rather than rejected. → [Configure OAuth App](/configure-o-auth-app)

***

## Next steps

<CardGroup cols={2}>
  <Card title="Move money through a wallet" icon="play" href="/quickstart/move-money-through-a-wallet">
    The full lifecycle end to end, as a runnable quickstart.
  </Card>

  <Card title="Spend accounts" icon="wallet" href="/features/spend-accounts">
    Create, fund, rename, and close sub-ledgers.
  </Card>

  <Card title="Funding sources" icon="link" href="/features/funding-sources">
    Link bank cards, bank accounts, and digital wallets.
  </Card>

  <Card title="Deposit funds" icon="banknote-arrow-down" href="/features/deposit-from-external-accounts">
    The full deposit input reference.
  </Card>

  <Card title="Withdraw funds" icon="banknote-arrow-up" href="/features/withdraw-to-external-account">
    Methods, timing, and error handling.
  </Card>

  <Card title="Transaction activity" icon="receipt" href="/features/get-all-transactions">
    Every movement in one filterable feed.
  </Card>
</CardGroup>