Idempotency for payment requests

Many Payments v3 API calls require idempotency.

The Payments API v3 supports API idempotency. This allows safe request retries (during the validity time window of the key) while only performing the requested action once.

For example, if there is a temporary connection issue, a request to create a payment could be safely retried several times without creating multiple payments.

📘
Always use a different idempotency key for different requests
You must use different idempotency keys for different requests. Reusing the same idempotency key will cause the subsequent requests to not be executed. Reuse of an idempotency key with a different payload, while the key is still valid, results in an error.

How to enable idempotency for requests

To use idempotency, where supported or required (for example, signed requests), add the idempotency-key header as shown in this example.

POST /v3/payments HTTP/1.1
Content-Type: application/json
Idempotency-Key: 3c9ae5ea-980f-4ebd-a027-04529942b95e
Tl-Signature: {SIGNATURE}
Authorization: Bearer {TOKEN}
....

📘
UUIDv4
We strongly advise that you use a UUID v4 for each idempotency key.
If you can't use a UUID and the endpoint doesn't require an authorisation token (such as the /v3/payments-provider-return endpoint), we recommend that you also include your client id in your idempotency key.

Scope and validity

Each idempotency key has a duration of 6 hours.

During the validity period, you can only send the same payload with the same idempotency key. If you do this, you receive an identical response.

If the payload is different, but the idempotency key is the same, you receive an error. The error is likely 422 or 409, explained below.

Error handling

These are some of the common errors associated with idempotency:

Error code	Error type	Detail	Solution
401	Unauthenticated	Invalid request signature.	Include the `Idempotency-Key` header when making requests to endpoints where idempotency is mandatory.
409	Idempotency-Key Concurrency Conflict	The Idempotency-Key value is being used for a concurrent request.	You submit a new request with a different idempotency key. This error occurs because another request with the same idempotency key is in flight. If you wait until the request is no longer in flight and make the same request with the same idempotency key, you receive an identical response.
422	Idempotency-Key Reuse	The Idempotency-Key value has already been used for a different request.	Make your request with a new idempotency key. Technically, you could also wait for the validity period of the idempotency key to end after 6 hours.

Updated about 2 months ago