Skip to main content
Network failures happen: a request times out, a connection drops, or your service retries before it sees the response. Without protection, a retried create call could produce a duplicate payment. Idempotency keys let you retry safely: Quidkey recognises the repeat and replays the original result instead of creating a duplicate.

​
Send an Idempotency Key

Add an Idempotency-Key header to create requests. Use a unique value (a UUID v4 is ideal) for each logical payment attempt. 
Idempotency-Key: 3f9a2c10-7b6e-4a1c-9d2f-8e5b1c4a6f3d
This matters most on create endpoints such as POST /api/v1/payment-requests:redirect, where a duplicate would create a second payment request. 
curl -X POST 'https://core.quidkey.com/api/v1/payment-requests:redirect' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 3f9a2c10-7b6e-4a1c-9d2f-8e5b1c4a6f3d' \
  -d '{
    "amount": 1999,
    "currency": "GBP",
    "locale": "en-GB"
  }'
Body abbreviated. See the Redirect guide for the full required payload.

​
How Replay Works

Quidkey scopes idempotency keys per merchant. When it sees a key it has handled before, it returns the original response rather than performing the action again.
ScenarioResult
Same key + same merchant, request already completedReplays the original response. No duplicate is created.
Same key, request still in flight (concurrent)409 IDEMPOTENT_REQUEST_IN_PROGRESS
Idempotency store unavailable503 IDEMPOTENCY_STORE_UNAVAILABLE (retryable)
Idempotency keys are scoped to your merchant. The same key value used by a different merchant is treated as an independent request.

​
Concurrent Requests

If two requests carrying the same key arrive before the first finishes, the second returns 409 IDEMPOTENT_REQUEST_IN_PROGRESS. The first request is still being processed, so wait briefly and retry with the same key to pick up the replayed result. 
{
  "success": false,
  "error": {
    "code": "IDEMPOTENT_REQUEST_IN_PROGRESS",
    "message": "A request with this idempotency key is already being processed."
  }
}

​
When the Store Is Unavailable

If Quidkey cannot reach the idempotency store, it fails closed rather than risk a duplicate, returning 503 IDEMPOTENCY_STORE_UNAVAILABLE. 
{
  "success": false,
  "error": {
    "code": "IDEMPOTENCY_STORE_UNAVAILABLE",
    "message": "The idempotency store is temporarily unavailable. Please retry."
  }
}
A 503 IDEMPOTENCY_STORE_UNAVAILABLE means the request was not processed. It is safe (and expected) to retry with the same idempotency key, ideally with exponential backoff.

​
Best Practices

Generate a fresh key when you start a new payment attempt. Persist it alongside your order so retries of that same attempt reuse it.
On a timeout or transient error, retry with the same key. A new key on retry defeats the protection and can create a duplicate.
If the customer deliberately starts over (e.g. a new checkout for a new basket), mint a new key, since it is a different logical attempt.

​
Next Steps

Errors

Status codes including 409 and 503

Accept a Payment (Redirect)

Create a redirect payment request

Authentication

Obtain and refresh access tokens

Webhooks

Receive payment results reliably