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 accounting rules in the Adyen payments platform take care of most potential double-processing issues that can impact payment modifications. For example, the following default rules apply:
- Captures: when partial captures are allowed, it is not possible to capture a higher amount than the authorized one.
- Refunds: when multiple refunds are allowed, by default the total refunded value cannot exceed the captured amount.
To minimize unwanted side effects when requests are duplicated, you can also take the following actions on your end:
- Implement asynchronous server-to-server webhooks. For example, this approach helps keep track of missing responses, a common consequence of a data transmission timeout.
- Enable idempotency in your API requests. 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 with the idempotency-key:<key> in the header.
The <key> is a unique identifier for the message with a maximum of 64 characters. We recommend using a UUID. If you do not receive a response (for example, in case of a timeout), you can safely retry the request with the same HTTP 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.
Make sure that you code for case-insensitive HTTP headers.
Here is an example of how to include the idempotency-key in a /payments request:
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 7 days after first submission (but may be retained for longer).
If you are targeting multiple regional endpoints 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 API credentials under the same account from accessing each others responses.
Lowering the access level for an API credential 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 422 – Unprocessable Entity 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 the Wikipedia article on 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-keyHTTP header.