Architecture One-Pager

Payment Checkout & Ledger Service · Solution Architecture v1.0 · open source, self-hosted on Kubernetes across two in-country data centres · Payments Platform Architecture · 2026-10 · 24 views · 18 architecture decision records

The authorization plane is allowed to fail; the book of record is not allowed to be wrong. A durable ordered event log is the only thing between them.

Everybody has pressed Pay now. What happens next is the part almost nobody sees, and it is harder than it looks for one reason: the money moves on networks the service does not own and cannot interrogate reliably. A card authorization can time out eight seconds after the issuer has already approved it, leaving the service genuinely unable to say whether the buyer has been charged. An account-to-account callback can arrive twice, out of order, or three hours late. A settlement file can turn up a day later and disagree with everything the service believed happened. Meanwhile the buyer is looking at a spinner and their instinct is to press the button again, the merchant is deciding whether to ship, and a regulator may ask in 2036 what the platform believed about this payment and when it believed it. A design that produces the right answer when the rails behave is not an architecture. It is a demo.

Split the system at the only boundary that matters. The authorization plane is stateless, latency-bound and allowed to fail: it authenticates the merchant, holds the payment intent's state machine, picks a provider from a versioned policy, calls it under a hard deadline, and answers the buyer. It holds no truth. The ledger plane is append-only double-entry, strongly consistent, synchronously replicated, slower by design, and allowed to be unavailable for writes for minutes without a buyer noticing — because nothing in it is on the buyer's path. Between them sits a durable ordered event log, which is the only coupling, and the reason a ledger partition does not become a checkout outage. Then accept the cost of that split honestly: there is a window in which a payment has succeeded in the world and is not yet in the books. Build the machinery that always closes it — an outcome poller for intents stuck in processing, a callback ingest that deduplicates and refuses illegal transitions, a daily settlement matcher whose file is the evidence, and a named break account for every amount that still cannot be explained. Treat unknown as an outcome rather than an error, never retry after one, declare idempotency separately at each boundary, and make every correction a new opposite-signed entry so the question "what did you believe, and when" always has an answer.

What it is, and what it is not

• The double-entry ledger as the only truth about money — not A status column on a payments table, with balances cached beside it
• Append-only, with corrections as new opposite entries — not An admin screen that can adjust a balance
• unknown as a first-class provider outcome — not A timeout treated as a failure and retried
• The settlement file as the evidence — not The provider's synchronous HTTP response as the truth
• Idempotency declared separately at each boundary — not One idempotency key assumed to cover every duplicate
• At-least-once webhooks with a per-object sequence — not Exactly-once delivery promised to merchants
• Unmatched value posted to a named, aged break account — not Unmatched value netted away at month end
• Fail closed on money movement — not Accept the payment and reconcile it later, optimistically

The decisions that are the architecture

1. Authorization plane ≠ ledger plane, coupled only by a durable event log (ADR-01) — The buyer-facing path is stateless, deadline-bound and permitted to decline, time out and fail closed; the book of record is append-only, strongly consistent and permitted to lag. A ledger outage becomes a balance that is behind, not a checkout that is down — and the price is a window the rest of the architecture exists to close.
2. The ledger is append-only double entry, balanced at write time (ADR-02) — Entries carry signed integer minor units, a transaction is rejected unless its entries sum to zero, and nothing is ever updated or deleted. Every balance, statement and report is a projection, so a number that cannot be derived from the ledger is a number the platform does not publish.
3. Idempotency is declared separately at every boundary (ADR-03) — The merchant's Idempotency-Key at the edge, the provider's own event identifier at the callback, the event identifier as a unique natural key on the ledger transaction, and a unique instruction key on the payout. Duplicate provider calls and duplicate ledger entries are different failures and need different keys.
4. unknown is an outcome, and there is never a retry after one (ADR-04) — A provider that does not answer within eight seconds leaves the intent in processing, which only an inbound signal or a reconciliation job may leave. A retry is the one action that can produce a double charge, and the budget is one per million attempts.
5. The provider's answer is a hint; the settlement file is the evidence (ADR-05) — Raw callbacks are persisted before they are parsed, deduplicated on the provider's event identifier, and checked against the state machine's legal transitions. What the daily file says is what the platform ultimately books.
6. Unmatched value is named, not netted (ADR-07) — Every settlement line is matched, broken or disputed. A break is posted to a named account, aged, owned and alarmed past 48 hours. An unexplained rupee on the books is a finding; an unexplained rupee off the books is a loss nobody will ever find.
7. Payment state is sharded by merchant; the ledger gives up a global sequence (ADR-08) — No synchronous cross-shard transaction exists anywhere in the payment path, and one large merchant's sale cannot consume another's capacity. The ledger is partitioned by period and account class, providing per-account ordering and a deterministic close rather than one total order.
8. At-least-once webhooks with a per-object sequence number (ADR-09) — The platform promises what it can provide and says so, gives a monotonic per-object sequence so a gap is detectable, and queues per merchant so a stalled endpoint delays nobody else. Ordered delivery would be kinder to naive handlers and would turn one slow merchant into everyone's backlog.
9. Keep the cardholder data environment small (ADR-11) — Card details travel from the buyer's browser into a separately clustered CDE and never enter the application zone. Everything downstream carries a token, keys never leave the HSM, and a full compromise of the application zone yields tokens rather than the ability to take money anywhere.
10. The platform holds merchant balances (ADR-13) — Refunds, disputes, fees and hold periods become natural, and the platform becomes custodian of other people's money — segregated accounts, float accounting, a licence and a much larger account model. The alternative is a thin pass-through that pushes refund funding onto merchants.
11. Dual control is a service in the path, not a policy in a document (ADR-14) — No sequence exists in which one authenticated human changes the books. The proposal and the approval are separate authenticated acts by different people, and the resulting instruction is signed in the HSM so the approval is evidence rather than a row somebody could write.
12. Self-managed open source in two in-country data centres (ADR-18) — Data localisation, PCI-DSS scope containment and a money path with no dependency a regulator has not approved outweigh the operational cost of running Kubernetes, Kafka, PostgreSQL and HSMs. Forty kilometres between sites is what makes synchronous replication and RPO 0 affordable.

Why this should still be right in ten years

The container platform, the broker, the relational store, the HSM vendor and every provider integration in this set will be replaced inside the platform's life. These are the properties that should outlast them.

• The boundary is not a technology. "The buyer-facing path may fail; the book of record may not be wrong" is a statement about where truth lives, not about Kafka or PostgreSQL. Every component named in this set can be replaced without touching that sentence.
• Double-entry is older than computing and will outlive this stack. The ledger's shape — balanced transactions, signed entries, named accounts, corrections as new entries — predates every technology here by centuries and is the one part of the design that will not need revisiting. Choosing it is choosing not to invent a money model.
• unknown will still be an outcome. New rails arrive constantly and every one of them will occasionally fail to say what happened. A design that treats ambiguity as a first-class state absorbs a new rail as an adapter; a design that treats it as an error rewrites itself for each one.
• Reconciliation outlives trust in any provider. The loop of believe, post, receive evidence, match, name the gap, correct and prove is independent of who the providers are, how many there are, and what protocol they speak. It is the control that makes every other optimism in the system safe.
• Evidence beats state. Storing the raw payload before parsing it, the policy version that made each routing decision and the posting rule version that booked each transaction means a question asked in 2036 is answerable from data rather than from code archaeology. Code changes; stored evidence does not.
• The blast radius is drawn, not asserted. A leaked merchant credential can take money only into that merchant's own settlement account, and an application-zone compromise yields tokens. Those are structural properties of where data and keys live, so they survive every refactor that respects the zones.

Non-functional targets

Every figure below is a stated assumption for this design, chosen to be defensible and arguable rather than measured. A reviewer who changes one can follow it to the decision that depends on it.

Scope

In scope

• Server-created payment intents with an explicit state machine, edge idempotency, separate authorize and capture, partial and multiple captures, and expiry with a provider void
• Card (network tokenised), account-to-account real-time transfer, wallet redirect and mandate debit behind one provider interface, with normalised outcomes including unknown
• Versioned declarative provider routing with health and cost inputs, circuit breaking per provider and per method, and a capped second attempt on retriable declines only
• Signed, deduplicated, legality-checked provider callbacks; an outcome poller for intents in processing; and a settlement matcher with authority to resolve payment state under constraint
• Full and partial refunds, voids of uncaptured authorizations, dispute and chargeback lifecycle with merchant debit and reversal, and receivables where a merchant balance goes negative
• A double-entry ledger as sole system of record: balanced at write, append-only, versioned posting rules, natural-key idempotency, daily trial balance and cash-position proof
• Daily settlement-file ingest with restatement handling, matching, a named and aged break account, and dual-control correction
• Merchant balances with per-risk-tier hold periods, T+1 payouts with unique instruction keys, sanctions holds, return handling and per-period merchant statements
• Signed at-least-once merchant webhooks with per-object sequence numbers, 72-hour retry, replay and a pull-based catch-up API
• A PCI-DSS-scoped cardholder data environment with a token vault and HSM key custody, and a browser-to-CDE path that bypasses the application zone
• Dual control on every privileged money operation, immutable operator audit with case references, masked-by-default operator views and logged elevation

Explicitly out of scope

• Card issuing, lending and credit, and in-person terminals with their EMV kernels, key injection and offline capture
• Acting as a payment network: the platform never clears or settles on its own rails
• Merchant onboarding, KYC, risk scoring and pricing configuration — a separate platform whose merchant records this service reads
• Fraud detection and decisioning as a product: the platform carries the hooks and the routing inputs, not the models
• Multi-currency settlement, FX rate custody and revaluation, marketplace splits and inter-merchant transfer — all deferred, and all of them reshape the ledger's account model
• The merchant's own storefront, order management and shipping decisions, including whether to ship on processing
• Tax calculation and invoice generation; the ledger records tax withheld, it does not compute liability

What a four-week prototype should prove

The prototype's job is to falsify the two central claims — that an asynchronously posted ledger can be made provably correct, and that the unknown outcome can be resolved without ever double-charging — on one rail and one merchant, not to build a platform.

1. One provider adapter against a simulator that can be told to approve, decline, time out silently, callback twice, callback out of order and omit a line from the settlement file.
2. The full intent state machine with edge idempotency, and a real append-only double-entry store that rejects an unbalanced transaction at write time.
3. The ledger poster consuming an event log with the event identifier as a unique natural key. Replay the whole log three times and prove the ledger is byte-identical.
4. A settlement matcher, a break account, and a daily trial balance. Inject a missing line, a duplicate line and a restated file, and show the books still balance with the gap named.
5. A property test that generates random sequences of approve / decline / timeout / duplicate-callback / late-callback and asserts, over ten thousand runs, that no intent ever produces two captures and no ledger transaction is ever posted twice.
6. Measure intent create and confirm latency at p50 and p99 under 500 attempts a second against the simulator, and measure the posting lag separately.
7. Deliberately excluded: disputes, payouts, multi-provider routing, the CDE, dashboards and anything with a user interface. If the above does not hold, none of them matter.

• Tell the provider simulator to accept the authorization and then never answer: does the intent end in processing, does the buyer's second tap create a second attempt, and is the payment resolved from the settlement file within the window?
• Deliver the same provider callback five times, two of them out of order and one for a state that is already terminal: does the ledger hold exactly one transaction, and is the ignored transition recorded rather than dropped?
• Omit one line from the settlement file, then deliver a restated file containing it the next day: does the break appear, age, and clear by a correcting transaction rather than an edit?
• Kill the ledger store mid-run for ten minutes: do authorizations keep succeeding, does posting lag alarm, and does the ledger drain to exactly the right state on recovery with nothing double-posted?
• Replay the entire event log three times into an empty ledger: is the result byte-identical each time, and does the trial balance come out at zero?
• Issue two concurrent refunds that together exceed the captured amount: is exactly one accepted, and does the rejection name the reason?
• Submit the same merchant Idempotency-Key with a different amount: is it a conflict rather than a second payment?
• Attempt a manual ledger correction with one operator account: does the ledger refuse it for want of a second signature?

Open risks, carried rather than hidden

The reasoning behind every component and technology choice is in the Architecture Decision Record: 18 records across 6 areas, each with the alternatives that lost and what the choice costs.