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

Loading…

Design a payment system: ledgers, webhooks, and idempotency

PaymentGuided Mode

Step 3 β€” Async Processing via an Event Queue

Request Flow

1

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.

2

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.

3

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