Every payment flow has a silent enemy: the network. Requests time out, connections drop, users panic, and click twice. What happens to your system when the same charge arrives more than once?

I used to think idempotency keys were one of those "nice-to-have backend things."

You know the kind you tell yourself you'll fix later. That thinking is dangerous.

When it comes to payments, idempotency isn't a feature; it's what prevents duplicate charges and inconsistent state.

The Problem: "The Double Tap"

Imagine this:

A user clicks "Pay"

The network is slow, or their Wi-Fi drops

They click "Pay" again

Your API receives two identical requests

If you're not handling this correctly:

The user gets charged twice

Your database ends up in a weird state

You lose user trust instantly

This doesn't require a bug.…