Insights · Article · Engineering · May 12, 2026
Designing safe retries across acquirers, double charge prevention, timeout ambiguity, and observability that finance reconcilers actually trust.
Payments fail in messy ways: gateways time out but capture later, mobile clients retry blindly, and webhooks arrive out of order. Idempotency keys are the contract between product engineering and money movement reality.
Standardize key generation at the business operation level, not per HTTP call. A user clicking pay twice should map to one intent with deterministic server behavior.
Retry policies should distinguish idempotent GET retries from POST captures. Exponential backoff helps networks; blind replays hurt ledgers.
Webhook verification and replay protection matter as much as client retries. Attackers forge callbacks; signatures and nonces belong in baseline libraries.
Partial failure modes include authorized but unsettled charges. State machines should be explicit in code and in customer support tools.
Observability should correlate a payment intent across services with one trace identifier finance can search. Scattered logs multiply manual investigations.
Load tests should include gateway latency injection. Orchestrators that collapse under slow acquirers cause incident weekends.
Finally, document edge cases for refunds and voids with the same rigor as captures. Reversals have their own race conditions.
We facilitate small-group sessions for customers and prospects without requiring a slide deck, focused on your stack, constraints, and the decisions you need to make next.
