Add idempotency to your payments requests
Many Payments v3 API calls require idempotency.
The Payments API v3 supports API idempotency. This allows you to attempt to resend requests while only performing the requested action once, for as long as the key is valid. Idempotency keys are valid for 30 days from creation.
For example, if there's 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 any requests after the first to not be executed. If you try to reuse of an idempotency key with a different payload, while the key is still valid, you get an error response.
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 {access_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 30 days.
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 type will usually be 422 or 409. See below for more information.
Retrying idempotent requests
Whenever you make a request to the Payments API that includes the Idempotency-Key
header, the response contains the Tl-Should-Retry
header. This is a Boolean field that tells you whether retrying the request with the same idempotency key could return a different result.
If Tl-Should-Retry
has a value of:
false
, you will receive the same response when you retry the request with the same idempotency key.true
, you might receive a different response when you retry the request with the same idempotency key.
If your response doesn't contain theTl-Should-Retry
header, the default behaviour is the same astrue
.
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 in the JOSE headers of the signature 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. | 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. | This should not happen if idempotent retries have been correctly implemented, so if this error is received it is advised not to attempt a retry. In your idempotent retry implementation ensure that the request body is identical on retries. |
Updated about 2 months ago