Accounts & funding
An account holds value. It has exactly one currency, belongs to one cardholder, and is what a card spends from.
The three balances
This is the part that most often gets built wrong, so it is worth stating plainly:
| Balance | Meaning |
|---|---|
ledger_balance | Money that has settled |
held_balance | Money reserved by approved authorizations that have not cleared |
available_balance | ledger_balance − held_balance — the spendable figure |
Show available_balance to end users. Reconcile against ledger_balance.
An interface built on ledger_balance displays money the cardholder cannot
actually spend, because it ignores holds placed by authorizations earlier the
same day. The result is a support ticket every time someone is declined while
the app says they have funds.
Holds are not debits. An approved authorization moves nothing; it reserves. The debit happens at clearing, typically the next day, and can be for a different amount — a restaurant tip is the everyday case.
Account status
An account is active or blocked. Blocking is reversible, does not touch the
balances, and makes every card funded by the account decline with
account_blocked until it is lifted.
In this section
- Creating accounts — opening an account against a cardholder, and why you do not need approved KYC to do it
- Funding and defunding — moving value in and out, idempotently
- Balances: ledger vs available — the full model, with a worked example through a complete authorization lifecycle