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 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 |
- Uses an http idempotency key with a unique identifier (provided by the merchant) |
- The header is only included on retries |
- The header is sent in all requests |
|
- Using the header changes processing from synchronous to asynchronous |
- 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.