How should I deal with the depreciation of Adyen's idempotency legacy solution?

Why are we changing our idempotency solution?

Adyen has developed a new idempotency framework that is able to optimally scale with the growth of Adyen’s platform. This new framework allows for increased synchronous processing, improved retry logic and better resilience.

With this new idempotency framework in place, Adyen will deprecate its legacy idempotency solution. Merchants making use of our legacy solution will require review of their integration and make updates where necessary.

What is the timeline for this change?
The deprecation of the legacy idempotency solution will be conducted in two stages:

Test environment – Deprecation of legacy solution by Wednesday July 1st
Live Environment – Deprecation of legacy solution by Tuesday September 15th

Our new idempotency framework is already available for merchants in the test and live environment. A timeline for both stages of the migration can be found below:

Up to June 30th 2020

July 1st 2020

Up to September 14th 2020

September 15th 2020

Test environment

Merchants upgrade test framework and migrate to the new solution

Adyen deprecates legacy solution

Live environment

Merchants upgrade live framework and migrate to the new solution

Adyen deprecates legacy solution

What are the main technical differences between both idempotency solutions?

The table below shows overview of the main technical differences:

Legacy idempotency framework

New idempotency framework

Http request header

Uses an http pragma key with a pragma directive header value

Head is only included on retries
Using the header changes processing from synchronous to asynchronous

Uses an http idempotency key with a unique identifier provided by you

Head is sent in all requests
Using the header does not affect synchronous processing

Retry handling

Sends a PROCESS_RETRY event code notification alongside the regular notification for requests

Sends the regular notification used for authorization requests

Error handling

Not applicable

Provides response errors for improved retry logic

Transaction Unique Identifier

Uses the merchant account and unique merchant reference to identify a specific transaction

Uses a merchant created idempotent key typically generated through the version 4 (random) UUID type*

*Please note that Adyen’s idempotency service is region specific and therefore the merchant provided unique idempotency keys should not be used cross-regionally in case you are processing in more than one region.

Where can I find more information about Adyen’s most recent idempotency solution?

Further information is available in our documentation, which you can find in our Adyen docs page here: API idempotency.

Please note that Adyen’s idempotency service is region specific and therefore the merchant provided unique idempotency keys should not be used cross-regionally in case you are processing in more than one region.

More details about idempotent keys refer to this page: key scope and validity time.

What are the next steps that I require to take for this change?

Our new idempotency framework is already available in the test and live environment. Your technical team or integrator can already start verifying your payments integration to assess the necessary changes and test it against our end points.