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 /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/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 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 Type | Detail | Cause |
---|---|---|
Unauthenticated | Invalid request signature | Missing idempotency-key header in endpoints for which idempotency is mandatory |
Idempotency-Key Concurrency Conflict | The idempotency key is already used in another request in progress | Another request with the same idempotency key is already in progress |
Idempotency-Key Reuse | The idempotency key was used for another request | Reuse of an idempotency key with a different request body in the validity time frame of the key |
Updated about 1 month ago