FAQ - Deprecation of Adyen’s idempotency legacy solution
Why are we changing our idempotency solution? Adyen has developed a new idempotency framework tha...
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
Merchants upgrade test framework and migrate to the new solution
Adyen deprecates legacy solution
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
- Sends a PROCESS_RETRY event code notification alongside the regular notification for requests
- Sends the regular notification used for authorization requests
- 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.
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 can also be found here or in the documentation link provided earlier within the response to this question.
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.
In case of any questions, please contact support (firstname.lastname@example.org).
How to check if my integration supports alphanumeric string references?
Adyen’s references are 16-character strings associated with a transaction/request. Although they ...
Adyen’s references are 16-character strings associated with a transaction/request. Although they are defined as strings, historically only numeric characters have been used for references generated by the Adyen platform. To support the growth in the volume of payments we are processing, references will consist of alphanumeric characters moving forward (i.e. 0-9, A-Z, a-z).
In order to ensure that your integration with Adyen is not impacted, we recommend that you perform a system test executing the following operations as applicable to Adyen's Test environment after May 15th 2019:
1. Classic Ecommerce:
- Make a direct API payment and process the response
- Make a Client Side Encryption payment and process the response
- Make a Hosted Payment Page request and process the response
- Make a payment and process the response using our Web, iOS or Android SDK or your direct Checkout API integration
3. Submit and process 3D Secure payments:
4. Point of Sale (POS):
6. Recurring Payments:
7. Third-party payouts:
8. Account Updater:
9. Payment Modifications:
10. Receive and manage Disputes:
11. Notifications (webhooks):
12. Process financial Reports:
Why am I not receiving notifications?
This can happen when your server did not accept a notification that we sent. When your server doe...
Manually accepting the notification
- Navigate to Account > Server communication.
- Click Troubleshoot, then Click here to view the notification that is failing. Here you will see which notification was not accepted. For more information on the event that triggered this notification, see Event codes.
- Click Manually accept notification.
Can my business submit Level 2/3 data?
By submitting Level 2/3 data you can cut your Interchange rates on US domestic transactions by up...
By submitting Level 2/3 data you can cut your Interchange rates on US domestic transactions by up to 90 basis points. At the same time, your shoppers will see additional information about their purchase on their credit card statement. For more information on which transactions are eligible, see Level 2/3 data qualification requirements.
Not all businesses can submit Level 2 and 3 data. If your business has one of the following Merchant Category Codes (MCC) you are not eligible for submitting Level 2/3 data, but it might be possible to pass another type of additional data to obtain interchange incentives (see third column):
|MCC||Card scheme||Data Type|
|3000-3299 (Airlines)||Mastercard and Visa||Airline|
|3300-3350 (Automobile / Vehicle Rental)||Visa||Car rental|
|3501-3999 (Hotels / Motels)||Mastercard and Visa||Lodging|
|4112 (Passenger Railways)||Mastercard and Visa||Unavailable|
|4411 (Steamship and Cruise Lines)||Visa||Unavailable|
|4511 (Airlines and Air Carriers)||Mastercard and Visa||Airline|
|4722 (Travel Agencies and Tour Operators)||Visa||Airline or Lodging or Car rental|
|5812 (Eating Places and Restaurants)||Mastercard and Visa||Unavailable|
|5814 (Fast Food Restaurants)||Visa||Unavailable|
|7011 (Lodging - Hotels, Motels, and Resorts)||Mastercard and Visa||Lodging|
|7361 (Employment Agencies, Temporary Help Services)||Mastercard||Temporary Services|
|7512 (Automobile Rental Agency)||Mastercard and Visa||Car rental|
|7513 (Automobile/Vehicle Rental)||Mastercard||Car rental|
|7519 (Automobile/Vehicle Rental)||Mastercard||Car rental|
Note: Data Type is the applicable data type to send for the merchant under that MCC.
What should I test before accepting live payments?
Before going live, we advise that you test: Payments with cards (each scheme) Payment notificati...
Before going live, we advise that you test:
- Payments with cards (each scheme)
- Payment notifications
- Payment modifications (if implemented)
- 3D Secure flow (if implemented)
- Local payment methods (if implemented)
- Test errors and refusal reasons
- Error handling
Once you are live, make sure that you change your API test endpoints to live endpoints and that your API test credentials are changed to live credentials.
How can I get additional data in Standard Notifications?
We send a set of default parameters in the Standard Notifications to help you sync your backoffic...
We send a set of default parameters in the Standard Notifications to help you sync your backoffice system with Adyen. In addition, you can add more data to notifications.
For this, in the Customer Area, go to Account > Server communication > Standard Notification, click Add (or edit it, if it is already enabled) > Additional Settings.
I can't see the PayPal shipping address
The most common reason is incorrectly configured information. Check that you are correctly sendin...
The most common reason is incorrectly configured information. Check that you are correctly sending all the following information:
For more information, refer to API Reference.
- deliveryAddress.deliveryAddressType = 1
For more information, refer to API Reference.
How do I configure additionalData in the authorise response?
You can get extra information about a payment in the additionalData object of the payment respons...
You can get extra information about a payment in the additionalData object of the payment response.
To enable or disable different options for additionalData, log in to the Customer Area, and then go to Account > API URLs > Additional data in API response.
You can preview the possible additionalData object and, once you are done, save the changes.
How does Adyen respond to Payment Modification requests?
Adyen replies to Payment Modification requests with an appropriate response message, for example,...
Adyen replies to Payment Modification requests with an appropriate response message, for example, capture-received, cancel-received, or refund-received. These messages mean the request is being processed.
The final status of the modification is sent via notifications. These notifications are sent as HTTP callbacks (webhooks) to the endpoints you set up on your server. For more information, refer to Notifications.
How do I connect a partner ecommerce or billing platform to Adyen?
If you are connecting to Adyen through one of our preferred partners for ecommerce (for example M...
If you are connecting to Adyen through one of our preferred partners for ecommerce (for example Magento, Salesforce, Hybris) or billing (for example Aria, Zuora, Recurly) and seeing an error code, refer to the following list of common connection errors:
|401||Incorrect ws user credentials entered.||
Log in to the Customer Area, reset the password for the ws user, and re-enter it.
For more information, refer to How to get the web service (WS) user password.
|403||ws user does not have the correct permissions.||
Refer to the partner platform's documentation for information on roles that need to be enabled. For more questions, contact Support or your implementation manager.
The request is formally valid, but semantically incorrect: the receiving server can read it, but cannot understand it.
One possible solution is to ensure you are using a valid test card for test transactions. Note that test cards will not work in your live environment, where we recommend using real cards with nominal values.
Another possible solution relates to recurring or subscription billing. In some cases, you may need to create a recurring contract before you can submit a recurring payment through Adyen.
For a complete list of possible error codes that you may receive from Adyen or Visa/Mastercard: