Design a payment system: ledgers, webhooks, and idempotency
Payment
Guided ModeStep 3 β Async Processing via an Event Queue
Request Flow
Gateway responds asynchronously
Most payment gateways do not respond synchronously β they return a PENDING state immediately and later deliver the final outcome via a webhook callback. We model this with a Queue that buffers gateway events.
Decoupled settlement
When the gateway confirms payment.succeeded, it fires an event onto the Queue. A separate settlement worker consumes the event and transitions the record from PENDING to SETTLED. This decouples capture from confirmation.
Queue provides durability
If the settlement worker is temporarily down when the gateway fires, the event waits in the Queue β no event is lost. Settlement happens automatically when the worker recovers.
Why We Need This
Synchronous settlement is fragile: if the gateway call takes 2 seconds and the user's connection drops at 1.9 seconds, we must retry β but the first request may have succeeded. Async processing via a queue sidesteps this entirely.
Key Insight
Treat the payment gateway as an unreliable external dependency. Accept its events into a durable queue and let a separate worker process them asynchronously β never wire the queue back into the payment orchestrator.
Step 3 of 7
