Your server sends a charge request. The connection drops before the response arrives. Did the charge happen? Without idempotency, you face a bad choice: retry and risk charging twice, or don’t and risk not charging at all.
What idempotency means
An operation is idempotent when performing it twice has the same effect as performing it once. Payment APIs implement this with an idempotency key — a unique value you attach to each logical operation. If the platform sees the same key again, it returns the original result instead of executing a second charge.
How to use keys correctly
- One key per logical operation, not per request. “Charge order 8471” keeps the same key across every retry. A new attempt to charge a different order gets a new key.
- Derive keys from your own identifiers. An order ID or invoice ID makes duplicates structurally impossible, and turns a duplicate-reference error into a useful signal that the first attempt succeeded.
- Store the key before you send. Persist it with the pending order so a crashed process can resume with the same key after restart.
- Retry with backoff. Same key, increasing delays, a sensible cap — then surface for manual review.
Where merchants get burned
The classic failure: generating a random key per HTTP request. Every timeout-retry becomes a fresh operation, and the double charge lands exactly when your infrastructure has a bad night — which is when retries fire most. The second failure: not handling the duplicate response, treating “already processed” as an error and refunding a perfectly good payment.
Test the ugly paths
In sandbox, simulate the timeout: send a request, kill the connection, retry with the same key. Confirm one charge exists. This ten-minute test prevents the support tickets that damage customer trust most — being charged twice.
Payixay’s API treats your payment reference as an idempotency signal — a duplicate reference returns a 409 rather than a second charge. Details in the developer overview.