Idempotency for Payments v3

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, 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.

Enable idempotency

To use idempotency, where supported or required (for example, 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}



We recommend that you use a UUIDv4 for each 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 payload is different, you get an error.

Error handling

These are some of the common errors associated with idempotency:

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.