Implement idempotent payment retries to prevent double-charges after network timeouts

Verified steps

1. Before initiating any payment API call, generate a stable idempotency key tied to the business operation (e.g., SHA-256 of order_id + attempt_number, or a UUID stored with the order record) — the key must be the same on retries for the same attempt, and different for new independent attempts.
2. Pass the idempotency key in the appropriate header: Stripe uses 'Idempotency-Key', Braintree uses a header or field, PayPal uses 'PayPal-Request-Id' — check each PSP's documentation for the exact header name and scope.
3. On any network-level timeout or 5xx response, retry using the identical idempotency key — the PSP will return the original response if the first request succeeded, preventing a duplicate charge.
4. On a 4xx response (bad request, card declined), do not retry with the same key after fixing the request — generate a new idempotency key for the corrected attempt, as the PSP may have stored the errored request against the old key.
5. Implement exponential backoff with jitter on retries: start at 1–2 seconds, double each attempt, add random jitter of ±20%, and cap at a maximum of 3–5 retry attempts before surfacing a failure to the user.
6. Store idempotency keys and their resolved outcomes in your database; on application restart or job re-queue, look up the stored key and outcome before making any API call to avoid redundant requests.