mufassall

Cheat sheet · Business processes

Double-entry ledger

14 min · Intermediate · mufassall.dtwin.uz/en/l/double-entry-ledger/

← Open the lesson

The problem

A marketplace keeps buyer wallets, pays sellers and takes a fee. A balance column updated in place loses money in races and cannot say where it went. A double-entry ledger records every movement as an entry whose postings sum to zero, derives balances from it and never rewrites history.

What you learn

  • Why a balance column updated in place loses updates and leaves no trail
  • Accounts, journal entries and postings that sum to zero, written in one transaction
  • Derived balances with a versioned cache, idempotency keys, holds and available balance
  • Refunds as reversal entries, one currency per sum, and a daily trial balance with alerts
Final scene

Diagram as code

The lesson's final design as text: paste it into Jira, GitLab, GitHub, Notion or your docs, where Mermaid renders by itself. There are D2 and PlantUML (Confluence, IntelliJ) versions too.

Mermaid: flowchart

flowchart LR
  n_app(["Buyer app"])
  n_api["Wallet API"]
  n_ledger[("Ledger")]
  n_balances[("Balance cache")]
  n_payout("Capture job")
  n_support(("Support agent"))
  n_rates>"FX rates"]
  n_checker("Trial balance")
  n_pager>"On-call alert"]
  n_app --> n_api
  n_api --> n_ledger
  n_api --> n_balances
  n_payout --> n_ledger
  n_support --> n_api
  n_api --> n_rates
  n_checker --> n_ledger
  n_checker --x n_pager

Mermaid: request sequence

sequenceDiagram
  participant n_api as Wallet API
  participant n_wallets as Wallets table
  participant n_ledger as Ledger
  participant n_balances as Balance cache
  participant n_app as Buyer app
  participant n_checker as Trial balance
  Note over n_api,n_wallets: A wallet is one number in one row
  n_api->>n_wallets: SELECT balance_minor FROM wallets WHERE user_id = 'u_42'#59;
  n_wallets-->>n_api: UPDATE 1
  Note over n_api,n_wallets: Two payments at once, one of them vanishes
  n_api->>n_wallets: 12:00:01.204 tx A read balance_minor=12000 (order 4500)
  Note over n_api,n_ledger: Every movement is an entry, its postings sum to zero
  n_api->>n_ledger: BEGIN#59;
  n_ledger-->>n_api: COMMIT
  Note over n_api,n_balances: The balance is a sum, cached with a version
  n_api->>n_balances: UPDATE account_balances
  n_balances-->>n_api: UPDATE 1
  Note over n_app,n_api: A retry posts the same payment twice
  n_app->>n_api: 14:02:10 POST /v1/orders/ord_5133/pay -#62; no answer in 5 s
  Note over n_app,n_api: One key per business operation
  n_app->>n_api: POST /v1/orders/ord_5133/pay HTTP/1.1
  n_api-->>n_app: HTTP/1.1 200 OK
  Note over n_app,n_api: Holds: ledger balance and available balance
  n_app->>n_api: GET /v1/wallets/u_58/balance HTTP/1.1
  n_api-->>n_app: HTTP/1.1 200 OK
  Note over n_api,n_ledger: A refund is a new entry, never an edit
  n_api->>n_ledger: INSERT INTO journal_entries (id, kind, ref, reverses)
  n_ledger-->>n_api: INSERT 0 3
  Note over n_api,n_ledger: One currency per sum, FX goes through accounts
  n_api->>n_ledger: INSERT INTO postings (entry_id, account, amount_minor, currency)
  n_ledger-->>n_api: COMMIT
  Note over n_checker,n_ledger: Every night: does everything still sum to zero?
  n_checker->>n_ledger: SELECT currency, SUM(amount_minor) AS total
  n_ledger-->>n_checker: trial balance 2026-11-17

D2

direction: right

n_app: "Buyer app" {
  shape: rectangle
}
n_api: "Wallet API" {
  shape: rectangle
}
n_ledger: "Ledger" {
  shape: cylinder
}
n_balances: "Balance cache" {
  shape: cylinder
}
n_payout: "Capture job" {
  shape: rectangle
  style.multiple: true
}
n_support: "Support agent" {
  shape: person
}
n_rates: "FX rates" {
  shape: cloud
}
n_checker: "Trial balance" {
  shape: rectangle
  style.multiple: true
}
n_pager: "On-call alert" {
  shape: cloud
}

n_app -> n_api
n_api -> n_ledger
n_api -> n_balances
n_payout -> n_ledger
n_support -> n_api
n_api -> n_rates
n_checker -> n_ledger
n_checker -> n_pager {
  target-arrowhead.shape: cross
}

PlantUML: request sequence

@startuml
participant "Wallet API" as n_api
database "Wallets table" as n_wallets
database "Ledger" as n_ledger
database "Balance cache" as n_balances
participant "Buyer app" as n_app
participant "Trial balance" as n_checker
note over n_api, n_wallets : A wallet is one number in one row
n_api -> n_wallets : SELECT balance_minor FROM wallets WHERE user_id = 'u_42';
n_wallets --> n_api : UPDATE 1
note over n_api, n_wallets : Two payments at once, one of them vanishes
n_api -> n_wallets : [duplicate] 12:00:01.204 tx A read balance_minor=12000 (order 4500)
note over n_api, n_ledger : Every movement is an entry, its postings sum to zero
n_api -> n_ledger : BEGIN;
n_ledger --> n_api : COMMIT
note over n_api, n_balances : The balance is a sum, cached with a version
n_api -> n_balances : UPDATE account_balances
n_balances --> n_api : UPDATE 1
note over n_app, n_api : A retry posts the same payment twice
n_app -> n_api : [duplicate] 14:02:10 POST /v1/orders/ord_5133/pay -> no answer in 5 s
note over n_app, n_api : One key per business operation
n_app -> n_api : POST /v1/orders/ord_5133/pay HTTP/1.1
n_api --> n_app : HTTP/1.1 200 OK
note over n_app, n_api : Holds: ledger balance and available balance
n_app -> n_api : GET /v1/wallets/u_58/balance HTTP/1.1
n_api --> n_app : HTTP/1.1 200 OK
note over n_api, n_ledger : A refund is a new entry, never an edit
n_api -> n_ledger : INSERT INTO journal_entries (id, kind, ref, reverses)
n_ledger --> n_api : INSERT 0 3
note over n_api, n_ledger : One currency per sum, FX goes through accounts
n_api -> n_ledger : INSERT INTO postings (entry_id, account, amount_minor, currency)
n_ledger --> n_api : COMMIT
note over n_checker, n_ledger : Every night: does everything still sum to zero?
n_checker -> n_ledger : SELECT currency, SUM(amount_minor) AS total
n_ledger --> n_checker : trial balance 2026-11-17
@enduml

PlantUML: components

@startuml
left to right direction
agent "Buyer app" as n_app
component "Wallet API" as n_api
database "Ledger" as n_ledger
database "Balance cache" as n_balances
collections "Capture job" as n_payout
actor "Support agent" as n_support
cloud "FX rates" as n_rates
collections "Trial balance" as n_checker
cloud "On-call alert" as n_pager
n_app --> n_api
n_api --> n_ledger
n_api --> n_balances
n_payout --> n_ledger
n_support --> n_api
n_api --> n_rates
n_checker --> n_ledger
n_checker -[#c62828]-> n_pager
@enduml

Recap

Six rules for money in a product.

1) Never keep money as a number overwritten in place. 2) Every movement is a journal entry whose postings sum to zero, inserted in one transaction. 3) Balances are sums of postings; a cache is fine if it has a version and can be rebuilt. 4) One idempotency key per business operation; holds lower the available balance until capture or expiry. 5) Undo with reversal entries, never UPDATE or DELETE; one currency per sum, FX through accounts. 6) Run a trial balance every day and page a person when it is not zero.

Numbers: at the start and at the end

MetricStartEnd
Unexplained money0 $0 $
Lost updates0/day0/day
Double charges0/day0/day
Balance read2 ms3 ms

Steps

  1. Case A wallet is one number in one row

    A buyer pays $45.00 for an order.

  2. Problem Two payments at once, one of them vanishes

    The buyer pays one order on the phone and another in the browser in the same second.

  3. Fix Every movement is an entry, its postings sum to zero

    The wallet becomes an account, and so do the seller and the platform's fee income.

  4. Fix The balance is a sum, cached with a version

    The true balance is SUM(amount_minor) of an account's postings.

  5. Problem A retry posts the same payment twice

    The pay request times out on a slow network.

  6. Fix One key per business operation

    The app creates the key once per payment, pay-ord_5133, and sends it on every retry.

  7. Fix Holds: ledger balance and available balance

    A buyer orders a $129.00 item that ships next week.

  8. Fix A refund is a new entry, never an edit

    Support refunds order ord_5120.

  9. Fix One currency per sum, FX goes through accounts

    A buyer pays 100.00 EUR into a USD wallet.

  10. Fix Every night: does everything still sum to zero?

    A nightly job runs the trial balance: the sum of all postings per currency must be exactly zero.

  11. Recap Recap

    Six rules for money in a product.

Terms

Double-entry ledger
Every money movement is one entry whose postings sum to zero: debit equals credit.
Trial balance
A regular check that all postings in each currency sum to exactly zero.
Reversal entry
A new entry with opposite postings that undoes an earlier one without editing it.