πŸ’¬
βœ‰οΈ
πŸ“Έ
▢️

Loading…

Design a payment system: ledgers, webhooks, and idempotency

PaymentGuided Mode

πŸ’³

Money must never be inconsistent.

Idempotency Β· Ledger Β· Webhooks Β· Reconciliation

Payment Systems β€” Why Money Is Hard

Request Flow

1

Money must never be inconsistent

Unlike a dropped search query or a missing feed post, a dropped payment is catastrophic. The user was charged but received nothing β€” or worse, charged twice. Every design decision in a payment system prioritises correctness over speed.

2

Three failure classes

(1) Duplicate charges β€” client retries after a network timeout but the first request already succeeded. (2) Lost payments β€” request arrived but the system crashed before persisting. (3) Phantom charges β€” charge recorded but downstream fulfilment never triggered.

3

What we'll build

A system that handles all three failure classes using Idempotency, Webhook Handler, an immutable Ledger Service, and a nightly Reconciliation Service.

Why We Need This

Payment networks like Stripe and Adyen are themselves distributed systems β€” they guarantee at-most-once processing on their side, but the connection between your service and theirs can fail at any point. Your system must be designed for partial failure at every layer.

Key Insight

The golden rule: it is always safer to fail a payment than to process it twice. Design every layer with that constraint in mind.

Overview