Idempotency ensures that the same API call doesn’t create duplicates, even when retried due to network issues.

​
Why it matters

Without idempotency, a connection timeout or retry can cause the same payment to be processed twice — resulting in double charges for your customer.

​
How it works

Diagram: first request is processed and cached (MISS); a retry with the same key returns the cached 201 result (HIT) without contacting the processor.

The first request carrying a given Idempotency-Key is processed and cached. Any retry with the same key returns the cached result — the customer is never charged twice.

1

Generate a unique key

For each payment, generate a UUID v4 as your idempotency key.
2

Send the key with your request

Add the Idempotency-Key header to your payment creation request:
3

Handle the response

  • First request → Creates the transaction normally
  • Subsequent requests with the same key → Returns the existing transaction without creating a new one

​
Key format

​
Best practices

Use UUID v4

UUID v4 guarantees sufficient uniqueness. Avoid time-based or sequential keys.

One key per operation

Create a new key for each new operation. Reuse the same key only for retries of the same request.

Store the key

Save the idempotency key alongside the transaction in your database for audit trails.

Don't reuse across operations

Using the same key for different operations may return unexpected results.

​
Common errors