hardDesignConceptMidSeniorStaff
The client retries a charge because your response timed out. The money must move once. What makes that true?
An idempotency key for retried charges is minted by the client per payment intent, claimed under a unique constraint in the same transaction as the charge, and used to replay the stored response on repeat. The API contract must define retention, in-flight retries and mismatched request bodies.
6 min readUpdated 2026-08-15
Answer
Short answer
Use an idempotency key that the client creates before the first charge attempt and sends on every retry. The server claims that key with a unique constraint in the same transaction that creates the charge, stores the original status and response, and replays that response for repeats. If the same key arrives with a different payment body, reject it; that is key reuse, not a safe retry.
Was this answer helpful?
Likely follow-ups
- A mobile client is reinstalled and loses its unsent key. What does a user who taps pay again get, and can the API help?
- Where in your stack is the key claimed if the charge is written by three services in a saga rather than one transaction?
- How would you document the guarantee so an integrator knows the difference between safe to retry and safe to repeat?
- A partner sends one key for a hundred different charges over a month. How does your API make that failure obvious rather than silently deduplicating real payments?
Related questions
- A client times out and retries your POST /payments call. How do you make that endpoint idempotent?hardAlso on retries5 min
- A dependency that normally answers in 80ms starts taking eight seconds. What in your service reacts, and in what order?hardAlso on retries7 min
- Ten million users need a green dot beside their name. What does that cost, and what happens when a phone loses signal without disconnecting?hardAlso on expiry5 min
- A payment API times out and the client retries. How do you guarantee the customer is not charged twice?hardAlso on retries6 min