Payment gateway integration done right
Authorize → capture → settle as an explicit state machine, with idempotent PSP calls, signed webhooks, daily reconciliation and chargebacks as compensating transactions.
What this design does
Integrating a PSP looks like one API call until production teaches you otherwise: webhooks arrive twice or never, captures time out after succeeding, and the money in your database disagrees with the money in your settlement report. This design treats the payment as a state machine with an idempotent transition log, verifies signed webhooks and dedupes them, reconciles daily against the PSP's own files, and models chargebacks as first-class compensating transactions rather than surprises.
The patterns it composes
- Authorization → capture → settle — payment is a state machine, not a boolean
- Idempotent payment — every PSP call carries an idempotency key — timeouts are retryable
- Circuit breaker + retry budget — a degraded PSP can't drag checkout down with it
- Reconciliation — internal ledger vs external settlement files, every day, automatically
- Chargeback as compensation — disputes unwind money with auditable reverse postings
Import it, attach your own numbers, and verify the design against failures — or read the engineering notes.