Brief #01 · Backend
Idempotent Payment API
Hard⏱ 15-20 hSoon
A payment API where a flaky network can retry as often as it likes, and the customer is still charged exactly once.
Outlines are free · building with tracking needs Pro
IThe briefFrom the team
Our checkout calls the payment provider, the provider times out, and the mobile app retries. Last month 214 customers were charged twice and support spent a week issuing refunds. Make double charges impossible, even when the app, the network and our own servers all misbehave at once.
What you'll build
- 1A
POST /paymentsendpoint that requires anIdempotency-Keyheader and stores each key with the request's hash. - 2A payment state machine (created → processing → succeeded / failed) with transitions enforced in the database.
- 3A fake payment provider you can make slow, flaky or duplicate its callbacks, to test against.
- 4Same key + same body returns the stored response; same key + different body returns 422.
- 5A load test that fires 1,000 concurrent retries of the same payment and proves one charge.
Step-by-step walkthrough
Walkthrough coming soon
This project's step-by-step walkthrough, with real outputs at every step, is still being written. You can read the brief and try it on your own meanwhile; tracking opens when the walkthrough is ready.
Done when
- No combination of retries, timeouts or crashes produces two charges in your test suite.
- Two requests racing with the same key never both reach the provider (row lock or unique constraint, not luck).
- Keys expire after 24 hours and the cleanup job is idempotent too.
- A README with a sequence diagram of the retry-after-timeout case.
Stretch goals
- Reconcile with the provider nightly and flag mismatches.
- Use the outbox pattern so the 'payment succeeded' event is never lost.