API idempotency

For our legacy instructions, see API idempotency (legacy).
The Adyen API supports  idempotency, allowing you to retry a request multiple times while only performing the action once. This helps avoid unwanted duplication in case of failures and retries. For example, in the case of a timeout error, it is possible to safely retry sending the same API payment call multiple times with the guarantee that the payment detail will only be charged once.

The Adyen API supports idempotency on POST requests (other request types such as GET, DELETE and PUT are idempotent by definition). 

Enable idempotency

To submit a request for idempotent processing, send a request including the Idempotency-Key:<key> in the header.  <key> is a unique identifier for the message with a maximum of 64 characters (we recommend a UUID). If you don't receive a response (for example, in case of a timeout), you can safely retry the request with the same header. If the Adyen payments platform already processed the request, the response to the first attempt will be returned without duplication. To verify that a request was processed idempotently, check the Idempotency-Key HTTP header returned in the response.

Key scope and validity time

Keys are stored at a company account level. The system checks that the idempotency keys are unique to the company account. Idempotency keys are valid for a minimum period of 31 days after first submission (but may be retained for longer).

If you are targeting multiple regional end-points simultaneously, idempotency keys will not be checked for duplication in other regions.

Security considerations

Generate idempotency keys using the version 4 (random) UUID type to prevent two web service users under the same account from accessing each others responses.

Lowering the access level for a web service user does not prevent them from retrieving past responses if the user still has access to previously used keys.

Error handling

Transient errors

In rare instances, you could receive a transient error. This is a temporary error that has no side effects and can be retried. For example, it could come from a race condition of sending two payment requests with the same idempotency key at the same time. One will end up being processed while the other will return a transient error.

The response will contain an HTTP header Transient-Error with the value true, which indicates that the request can be retried at a later time using the same idempotency key. If the API does not return a transient error header, or returns a header with a value of false, do not retry the request. If you submit a duplicate request before the first request has completed, the API returns an HTTP 409 – Conflict status with the error code 704: “request already processed or in progress”.

Retries and exponential backoff

Use an exponential backoff strategy when retrying transactions to avoid flooding the API and running into rate-limiting. See https://en.wikipedia.org/wiki/Exponential_backoff for more information.

Designing for resilience

To enable idempotent behavior, Adyen must retain a consistent, stateful data store to compare each request against. Idempotent processing relies on this data store being available. In the unlikely event that this data store should become unavailable, the API returns an HTTP 503 – Service Unavailable status with the error code 703: “required resource temporarily unavailable”. The system marks the request as a transient error (see above).

If there are many of these responses, you can either:

  • Pause processing and retry the requests later (if this is feasible).
  • Fall back to non-idempotent processing by not submitting the Idempotency-Key header.