Using the Idempotency-Key Header

The Idempotency-Key header ensures that a request can be safely retried without creating duplicate operations. It is especially useful for requests that perform actions such as creating payments, issuing refunds, or voiding transactions.

Without an idempotency mechanism, network interruptions, client restarts, or repeated retry logic might cause the same request to be processed multiple times, potentially creating duplicate payments or operations. By including a unique key, you can safely retry a request and be confident it will only execute once.

How Idempotency Works

When you include the Idempotency-Key header in a request:

ePay stores the response for the given combination of Key, Endpoint, and HTTP Verb.
If the exact same request (same endpoint, method, and key) is received again within 24 hours, we do not perform the operation again.
Instead, ePay returns the original response, along with the header:
```
Idempotent-Replayed: true
```
After 24 hours, the cached response expires, and the idempotency key will no longer apply.

To see which endpoints support idempotency key, take a look at our API.

Scope: The idempotency key is scoped per combination of key + endpoint + HTTP verb, meaning the same key on a different endpoint or method will not replay the original response.

When to Use Idempotency Keys

Include Idempotency-Key for any request where a duplicate operation could have negative effects, such as:

Creating payments or subscriptions
Issuing refunds
Voiding transactions
Any write operation that changes data or triggers money movement

GET requests are naturally safe to retry, so idempotency keys are typically most useful for POST, PUT, or DELETE requests.

How to Use It

Generate a unique key (for example, a UUID) for each operation:
```
Idempotency-Key: c4f5e8d2-1234-5678-90ab-cdef12345678
```

Include the key in your request header:

POST /public/api/v1/cit
Idempotency-Key: c4f5e8d2-1234-5678-90ab-cdef12345678
Content-Type: application/json

Handle network retries:
- If the client times out or loses the connection before receiving a response, resend the exact same request with the same Idempotency-Key.
- The server will return the original response once more.

Example Use Case

Retry a Payment Creation Request

If network issues occur while submitting a payment, you can safely retry:

POST /public/api/v1/cit
{
  "pointOfSaleId": "0192473a-e381-705c-b61c-fc2ac9624afc",
  "amount": 20000,
  "currency": "DKK"
}

Headers

Idempotency-Key: 4a1f2eb3-911b-40cd-9bcb-be321aa7a123
Content-Type: application/json

If the client resends this request using the same key within 24 hours, ePay does not create a second payment but responds with:

HTTP/1.1 200 OK
Idempotent-Replayed: true

Best Practices

Always generate a new key per unique operation (for example, one key per payment or refund).
Persist keys on your side until you confirm the final state of the operation.
If an operation must truly be re-executed (for example, a second payment), use a new idempotency key.
Keep in mind that idempotency keys are case-sensitive strings and must remain unique for each intended operation.

By adopting idempotency keys, you can make your integration more resilient to timeouts, connection issues, and client retries—ensuring a consistent experience for both your application and your customers.

How Idempotency Works​

When to Use Idempotency Keys​

How to Use It​

Example Use Case​

Retry a Payment Creation Request​