Idempotency key
An idempotency key is a unique value a merchant attaches to a payment request so that the provider processes it only once, even if the request is sent again after a timeout. A repeated request with the same key returns the original result instead of creating a second payment.
How it works
An idempotency key travels with the request, usually in a header or a field. The provider remembers the key and the result. When the same key arrives again, it replies with the stored result. An illustrative exchange:
request key: PAY-5E6F amount: 1500 -> created C-77001
timeout, merchant retries
request key: PAY-5E6F amount: 1500 -> same result C-77001
Without the key, the retry could create a second provider payment, C-77002, for one player action.
Why it matters
Retries are normal: networks time out and platforms resend. Not every provider supports idempotency keys, and not every integration sends them. The result is duplicate requests, which providers then decline or, worse, process twice. On one anonymised merchant day, 6.9% of declined transactions were fixable by the merchant, including duplicates, invalid requests and currencies not enabled.
How to spot it
Search your log for one merchant reference that maps to two provider IDs. Look for identical amounts from the same player within seconds. Then check whether your integration sends a key to that provider, and whether the provider documents honouring it.
Related terms
Duplicate notification · Callback · Merchant log · Decline reason · Payment reconciliation in Reconora
Try it on one day of your data
One day of your data, reconciled, and the report stays with you whether or not you continue.
Updated