Designing reliable payment APIs
Webhooks and queues that tolerate duplicates, delays and failures without corrupting state.
- An external provider sends an event; the endpoint verifies its signature before trusting it.
- An idempotency key guarantees the same event is never applied twice.
- Work is pushed to a queue and processed by workers with retries and backoff.
- Only then does business state change — an invoice is paid, an order moves forward.
Context
PayX sits between merchants and payment providers: a merchant issues an invoice, the customer pays, and the merchant’s backend must learn about it.
Technical challenge
Callbacks can arrive late, twice or not at all, and a payment must never be applied twice or lost.
Chosen solution
The pattern behind the flow: verify an incoming event before trusting it, apply it idempotently, and run slow work in queued jobs with retries — with every transaction and commission recorded.
Trade-offs
Asynchronous processing means a merchant may see a payment a moment after it happens rather than instantly — the price of never crediting an invoice twice.
Result
Merchants integrate through one developer API with invoices, callbacks, commissions and transaction tracking.
All deep dives