The scariest bug in commerce isn't a payment that fails. It's a payment that succeeds twice. And it hides in the most innocent place imaginable: a customer with a flaky connection tapping "Pay" one more time.
Killing that bug in a system that takes real money was one of the defining engineering problems in Saturdays, the food-delivery marketplace I shipped to production.
How the double charge happens
Networks are unreliable, so clients retry. A customer taps Pay, the response gets lost on the way back, the app assumes it failed and tries again — and now you've charged them twice for one order. The naive fix is to hope it doesn't happen. In production, with real traffic on real mobile networks, it absolutely happens.
You can't out-optimize an unreliable network. You have to design for the retry.
The idempotency key
The fix is a guarantee the server makes: every payment attempt carries a unique idempotency key, and the promise is — the first time I see this key I do the work; every time after, I return the same result without doing it again.
Suddenly a retry is safe. The client can fire the identical request ten times over a dropping connection and the customer is charged exactly once. In Saturdays, the same idempotency key rides along the entire ordering-to-payment path, across two independent gateways, so a retried tap can never become a double charge.
That one property is what let me treat the payment flow as genuinely reliable instead of merely usually-fine.
Why it's bigger than payments
Idempotency isn't a payments trick — it's how you make any operation safe to repeat, and the moment retries exist in your system (they always do), it stops being optional. Submitting a form, processing a webhook, kicking off a job, charging a card: if doing it twice is worse than doing it once, it needs to be idempotent.
Most engineers meet this concept in a textbook and file it away. You really learn it the first time you're responsible for other people's money and realize "it usually works" would be a headline-grade failure.
Building checkout for live traffic turned idempotency from a term I knew into a discipline I reach for by reflex. The full reliability breakdown is on the project page.
👉 See the system: www.divyakush.com/projects/saturdays
Divyakush Punjabi — Full-Stack & AI Systems Engineer
🌐 https://www.divyakush.com · 💼 LinkedIn · 💻 GitHub
Top comments (0)