Payment Checkout & Ledger Service  ·  View 07 of 24  ·  Structure

Layered Architecture

Eight layers, and a single layer called Coupling that exists to keep the two halves apart.

Editable source SVG draw.io All views
Clients Checkout SDK buyer browser Merchant server Merchant dashboard Finance ops console Edge API gateway Envoy · mTLS Credential auth scoped keys Idempotency keys 24 h Per-merchant quota fair queue Authorization Intent service state machine Routing engine policy vN Provider adapters Step-up orchestration 3-DS · collect Coupling Durable event log Kafka · per-intent order Ledger Posting rules versioned Ledger poster balance at write Ledger store append only Close of books trial balance Money ops Callback ingest Outcome poller Settlement matcher Payout engine Webhook delivery Projections Merchant balances rebuildable Statements Analytics marts Cross-cutting HSM key custody Token vault PCI CDE Immutable audit Observability Config & policy versions authenticated events post fan-out project detokenise Layered Architecture External / third party Application we own Interface / broker Security / platform Data store Queue / topic synchronous event / async batch The only path from Authorization to Ledger is the event log. No layer above Coupling writes the books directly. v 1.0 · owner Payments Platform Architecture · date 2026-10

The critical design decision, drawn

  • The only path from Authorization to Ledger is the durable event log. No layer above Coupling writes the books, and no layer below it is on the buyer's request (ADR-01).
  • A diagram elsewhere in this set showing a money-operations service writing the ledger directly would contradict the architecture, not extend it.

Decisions

  • Posting rules are versioned artefacts in the Ledger layer, not code scattered through services: the reason for an entry must be reconstructable in 2036 (ADR-02).
  • Idempotency keys live at the Edge, where the merchant's key arrives, and are a different mechanism from the ledger's natural key (ADR-03).

Risks

  • The event log is now a single structural dependency for durability. Its failure mode is drawn in view 24: authorization continues, the ledger lags, and nothing is reported as settled.
◀  Journey — Finance Ops Closes the Day All views Platform Components (C4 Level 2)  ▶
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 records07-layered-architecture