Balances & transactions
The ledger โ how much money you (or a customer) have, and every entry that got it there.
A Balance tracks how much money is available (and how much is held) per customer per currency. A Balance Transaction is one ledger entry โ every charge, refund, payout, and transfer posts one.
How it works
- Every money-moving action โ a successful Charge, a Refund, a Payout โ automatically posts a Balance Transaction and updates the relevant Balance.
- Balances exist both at the application/country level (your overall funds in that market) and per customer (their individual wallet).
- Funds can be
available(usable now) orheld(pending settlement, a hold, or a dispute) โ the split is always visible on the Balance. - Retrieve a single Balance, or list every Balance. Balance Transactions can be listed or retrieved individually.
Think of the Balance as the current total, and Balance Transactions as the bank statement that explains how it got there โ always reconcile against the transactions, not just the balance number.
Record-only rows
Some rows record money PaymentGateway does not hold: what you owe a connected
account on a destination charge, the application fee you earned from it, and
payments into your own provider account. They are listed so every part of a
payment is visible, and each carries record_only: true (plane: "memo").
They never add into a balance, so filter them out with
filter[record_only]=false when you total amounts. A charge's balance
transactions also include those of its refunds, disputes and application fee
refunds.
Common use cases
- Showing a customer their current wallet balance in your app.
- Reconciling "why did our available balance drop by this amount today?"
- Confirming a payout actually posted before considering it settled.