Payment System diagram template
A payment flow with idempotent APIs, a ledger, a provider gateway and reconciliation.
About this design
A payment system is judged by what it never does: charge twice, lose a transaction, or let two records disagree. This template routes every request through an API that demands an idempotency key, so a retried call returns the original result. A payment service moves a payment through explicit states and calls an external processor, while a double-entry ledger records each movement as balanced debits and credits that are never updated, only appended. Results from the processor arrive asynchronously through webhooks, which a dedicated handler verifies and applies. A nightly reconciliation job compares the ledger with the processor's settlement files and flags every difference for a human. Use the diagram to discuss timeouts with unknown outcomes, retry safety, PCI scope reduction through tokenisation, and why money amounts are stored as integer minor units rather than floating point.
Diagram as text
This is the source of the diagram, in the ArchBoard diagram DSL. Paste it into Tools, Diagram from text to rebuild or change it.
title "Payment system"
direction LR
client "Merchant app" -> gateway "API gateway" -> service pay "Payment service"
pay -> db postgres "Payments DB"
pay -> db postgres "Ledger"
pay -> external stripe "Payment processor"
payment-processor -[webhook]-> service hook "Webhook handler" -> pay
cron "Reconciliation" -> ledger
reconciliation -> storage s3 "Settlement files"
