Designing Idempotent APIs for Payment Systems

Why idempotency isn’t optional

The first time a retried request double-charged a customer, I learned this lesson the expensive way. Networks are unreliable, clients retry, and load balancers occasionally deliver the same request twice. If your payment endpoint isn’t idempotent, that’s not a hypothetical bug — it’s a matter of when.

My approach in Spring Boot services is to require an idempotency key header on every mutating request, store it alongside the resulting response in a dedicated table, and short-circuit duplicate keys before they touch business logic. It’s a small amount of infrastructure that removes an entire category of production incidents.

Keeping it out of your domain logic

The trap is scattering idempotency checks across every handler. I wrap it in a single filter that intercepts the request, checks the store, and replays the cached response on a hit. Everything downstream stays blissfully unaware.