- 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
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 passingsource: "REWARDS_BALANCE" — the only balance besides cash that withdrawCashBalance accepts.
Prepayment balance
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.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 withdepositType: "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.“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.isDefault.
The three numbers
Each spend account tracks three amounts, and they answer different questions:
Check
availableCashBalance before any high-volume run. totalCashBalance minus available is money in flight.
Managing them
→ Spend Accounts · Get Spend Accounts
Every way money moves
In — depositing from external sources
depositCashBalance pulls from a linked funding source into a balance you choose.
- Funding source:
bankAccountId,bankCardId, orpaypalVaultId, all retrieved fromgetWallet. - Destination:
depositTypeofCASH_BALANCE,GIFT_CARD_BALANCE, orRESERVE_BALANCE. - Spend account: with
CASH_BALANCE, target one explicitly usinguserCashBalanceId.
balances object reflects what’s available immediately, so read it rather than assuming the full amount landed.
→ Deposit Funds From External Accounts · 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
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.
Around — to another Fluz user
Sending to a different Fluz account is a separate operation. Address the destination byaccountId, or by your own identifier with externalReferenceId — see Managing External Reference IDs. The recipient must have authorized your application.
→ Account to Account Transfers · Recipient Lookup
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:
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.
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.Reading balances
Two queries, two granularities: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 · View Funding Sources
Idempotency
Every money-moving mutation — deposit, redemption, internal transfer, account-to-account transfer, withdrawal — requires a unique, client-generatedidempotencyKey.
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
Scopes
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
Next steps
Move money through a wallet
The full lifecycle end to end, as a runnable quickstart.
Spend accounts
Create, fund, rename, and close sub-ledgers.
Funding sources
Link bank cards, bank accounts, and digital wallets.
Deposit funds
The full deposit input reference.
Withdraw funds
Methods, timing, and error handling.
Transaction activity
Every movement in one filterable feed.