# 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](https://reconora.com/glossary/duplicate-notification) · [Callback](https://reconora.com/glossary/callback) · [Merchant log](https://reconora.com/glossary/merchant-log) · [Decline reason](https://reconora.com/glossary/decline-reason) · [Payment reconciliation in Reconora](https://reconora.com/product/reconciliation)

[Start a free pilot](https://reconora.com/pilot) · [Book a 20-min call](https://calendar.google.com/calendar/appointments/schedules/AcZssZ2qcg1D27PGeYQ91fuYaSo7oy6D4tQ0onTGhC2mSdAWZpCuMUozMxIan4qYWtSk56H-hZTTZAC7)

---
Source: https://reconora.com/glossary/idempotency-key · Updated 2026-10-18
