Search

Are you looking for test card numbers?

Would you like to contact support?

Developer-resource icon

API idempotency (legacy)

In an API context, idempotency (or idempotence) means that making the same request many times produces the same effect as making it only once. The operation is free of side effects. This consistent behavior helps avoid unwanted duplication in case of failures and operation retries. For example, in the case of a timeout error, it is possible to safely retry sending the same API payment authorisation call many times. When the call successfully delivers its message, only one response action is executed, and the payment is not duplicated.

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 to payment authorisations:

  • One authorisation = One capture. Only one capture is accepted for an authorisation.
  • It is not possible to capture a higher amount than the authorised one.

As for refunds:

  • Whereas multiple refunds are allowed, by default the total refunded value cannot exceed the captured amount.

To minimize the risk of unwanted side effects and duplication, you can take the following actions on your end:

  • Implement asynchronous server-to-server notifications to return API request results. For example, this approach helps keep track of missing responses, a common consequence of a data transmission timeout.

  • Implement idempotency and include in your API request the additional Pragma HTTP header key and the corresponding pragma-directive header value.

Idempotency is not enabled by default for your merchant account. To enable it, contact the Support Team.

Enable Idempotency

To use the idempotency property of the Adyen API, provide your merchant account and unique merchant reference sent with your request.

For subsequent retries, the same unique merchant reference of the first request needs to be used in order to check if the first one was already processed.

Pragma HTTP header

To enable idempotency, set the Pragma HTTP header to:

  • Trigger idempotent behavior.
  • Report status information.

Using the pragma header will result in asynchronous processing.

Pragma header key and pragma-directive header value

When a request you send receives no response, you can enable idempotent behavior by including the  Pragma  HTTP header key and the appropriate pragma-directive value in your request.

To enable idempotency, you need to set the pragma-directive value to process-retry.

HTTP header key name HTTP header value name Syntax Example
Pragma pragma-directive
Pragma: pragma-directive
Pragma: process-retry

Multiple pragma directive values are comma-separated.

Code example

The following CURL call to the Adyen test payment endpoint authenticates the user and adds the pragma: process-retry HTTP header to the request.

curl -w "\n\nRequest size: %{size_request} \nResponse size: %{size_download} \nResponse code: %{http_code} \nTime total: %{time_total} [namelookup tcpconnect appconnect starttransfer]=[%{time_namelookup} %{time_connect} %{time_appconnect} %{time_starttransfer}]\n\n" \ 
--basic --verbose --output result.xml \ 
--header "content-type: text/xml" \ 
--header "pragma: process-retry" \ 
--data-binary @payment.xml \ 
--user "ws@Company.{YourCompanyAccount}:{yourPassword}" \ 
--url "https://pal-test.adyen.com/pal/servlet/Payment/v46" \ 
&& xmllint --format result.xml --output result.xml

Retry idempotent submission

Sometimes, you may want to retry sending a transaction whose status is not finalized yet, and at the same time you want to avoid processing a transaction multiple times.

This flow consists of the following steps:

Request

When we receive a request that includes the Pragma: process-retry HTTP header, our system performs a lookup to determine whether:

  • The request has already been processed - In this case:

    • No further processing occurs.
    • We send you a PROCESS_RETRY event code notification, besides the standard scheduled notification for this operation.
  • The request has not been processed yet - In this case:

    • The request is processed as if it were the initial request.
    • We send you the standard scheduled notification for this operation, and a PROCESS_RETRY event code notification.

Response

When you submit a request with the Pragma: process-retry HTTP header, you receive a response with a PaymentResult element.

The request has already been processed:

When the request has already been processed, the pspReference in the response is different from the pspReference in the initial request because the initial request missed its synchronous response.

To reconcile the association between the initial request and the corresponding retry, our system sends you a notification with the eventCode value set to PROCESS_RETRY.

This notification contains both pspReference values:

  • pspReference: this field holds the retry request pspReference value.
  • originalReference: this field holds initial request pspReference value.

The request has not been processed yet

When the request has not been processed yet, the pspReference in the response is the same as the pspReference in the initial request.

Therefore, the notification with the eventCode value set to PROCESS_RETRY you receive from Adyen includes a pspReference value matching the one in the corresponding initial request.