Learn how to use idempotency in your requests.

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

For example, a create payment request in case of transient connection issue could be safely retried several times without having to worry about creating multiple payments.


Always use different idempotency key for different requests

Make sure to always use different idempotency keys for different requests. Reusing the same idempotency key will cause the subsequent requests to not be executed.
In case of reuse of an idempotency key with a different payload during the validity of the key will result in an error.

Enable idempotency

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

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


UUIDv4 as idempotency key

We recommend the usage of an UUIDv4 as idempotency key.

Scope and validity


Idempotency key expiry

An idempotency key has a duration of 6 hours. During this period you can only send the same payload with the same idempotency key. If the request is different it results in an error.

Error handling

Some of the common errors associated with idempotency can be found below:

Error TypeDetailCause
UnauthenticatedInvalid request signatureMissing idempotency-key header in endpoints for which idempotency is mandatory
Idempotency-Key Concurrency ConflictThe idempotency key is already used in another request in progressAnother request with the same idempotency key is already in progress
Idempotency-Key ReuseThe idempotency key was used for another requestReuse of an idempotency key with a different request body in the validity time frame of the key

Learn more about Error types.

Did this page help you?