Fintech, marketplaces, apps with balances
Wallets and stored value
Customer balances that can never go below zero, overdraft facilities where you extend them, and a statement that reconciles line by line.
The problem
What goes wrong without a ledger
A wallet is a liability to a customer. If two spends race for the same balance, or a refund is applied twice, the books say one thing and the customer’s money says another. Most wallet bugs are exactly this: a balance that was true a millisecond ago.
How it works on Ledger
The shape of the books
One account per customer, floored at zero
Every wallet declares that it may not go negative. A spend that would breach the floor is refused by the database, however many requests arrive at once.
Top-ups and spends as balanced transactions
A top-up moves value from your funding account to the wallet; a spend moves it out. Each is one record with a source and a destination.
Freeze without losing anything
A frozen wallet rejects movement and keeps its full history. Nothing is deleted when a dispute is open.
Statements that do not shift
Pages of entries are stable as new activity arrives, so an exported statement is the same statement a customer sees.
POST /v1/transactions # a spend of 12.50 from a wallet
{
"description": "order 8813",
"entries": [
{ "account_id": wallet, "direction": "debit", "amount": "12.50" },
{ "account_id": revenue, "direction": "credit", "amount": "12.50" }
]
}
# if the wallet holds 10.00: 422 INSUFFICIENT_AVAILABLE, nothing writtenWhat you get
Outcomes, and the guarantees behind them
- No phantom overdrafts under concurrent traffic.
- A refund that is retried cannot credit twice.
- Total customer liability is derivable from the ledger at any moment.
Questions
Asked about this use case
Can I offer an overdraft to some customers?
Yes. Give that account a negative floor equal to the agreed limit. The floor is checked on the net position of a transaction, so a fee and a payment in one transaction are judged together.
How do I handle a disputed transaction?
Freeze the account if you need to, and post a reversing transaction when the dispute resolves. Both the original and the reversal stay on the books.
Free today. Access is provisioned personally by RODMENA.
Tell us what you keep books of and we will set up a tenant, mint your first key and walk you through the tour.