PayPal's product looks like a balance. Underneath, a balance is a dangerous fiction if it is a single row you update in place while the other side of the transfer lives in another database, another country, or another bank. PayPal moves value among wallets, cards, holds, disputes, and currencies. Engineering writing from PayPal and the broader payments industry converges on the same primitive: an append-only ledger of entries (often double-entry) from which balances are derived. The company that popularized "emailing money" had to become a bookkeeping system that could survive retries, partial failures, and regulators who ask how a number was reached.
Entries, instruments, and holds
A capture, a refund, a chargeback, a currency conversion, a hold for pending clearance: each is a journal-shaped event with accounts that must balance. Mutable available_balance is a cache. If you decrement it without a matching entry, you have invented money or destroyed it. Holds are first-class: pending does not mean available, and available does not mean settled. PayPal's customer-facing delays are often this state machine, not "the servers are slow."
Idempotency belongs at the ledger API. A timeout on "send $20" cannot be a maybe. The ledger needs a client-supplied key or a deterministic transaction id so a retry posts zero extra entries. That is the same lesson Stripe later made famous; PayPal had to learn it at global wallet scale first.
Movement across systems
Not every hop is inside PayPal's ledger. Card networks, ACH, and local payment methods are other ledgers you cannot append to. The internal journal has to record what you intended, what the network acknowledged, and what you still owe to reconcile. Nightly (and continuous) recon is not accounting theater. It is how you find the entry that posted internally when the processor declined, or the opposite.
Multi-currency adds rounding and nostro accounts. If you use floating point, you will create pennies that cannot be explained. Integer minor units and explicit FX entries are boring and mandatory.
Failure modes of wallet ledgers
The concrete failure is writing the processor first and the ledger second, then dying. The card is charged; PayPal's books do not show it; support refunds from a UI that posts a second time. Mid-size steal: pick an order (usually ledger intent, then processor, then ledger completion) and a recovery worker that can finish or compensate from either side's records.
Operational gotcha: a support tool that UPDATEs a balance to "fix" a ticket. That tool is now a second, unaudited ledger. Freeze humans to the same posting APIs. Another is mixing product events ("user clicked send") with accounting events in one table and then using it for both analytics and money. Split them. Clock skew across regions will reorder entries if you use wall time as the journal order; use a monotonic sequence per account or a proper transaction id. Disputes that post before the original capture is visible in a replica will create negative inventory of money in a read-your-writes sense. Serve balances from a replica only if you can tolerate that, which you usually cannot on the money page. If you operate multiple ledgers (wallet vs. merchant vs. treasury), define the accounts that stitch them. Unstitched ledgers are how finance and engineering each have a number and both are sure.
What you can borrow
- Derive balances from immutable entries; treat the integer on the profile page as a projection.
- Model holds and pending as states with entries, not as a boolean on the user.
- Reconcile continuously against processor reports; the first unexplained penny is a bug, not a rounding story.
- Ban support UPDATEs against balances; every fix is a posting.