build a robust payment integration with Adyen

How to build a robust payment integration with Adyen? Tips, tricks and challenges

commercetools author image Stephanie Wittmann
Stephanie Wittmann
Head of Communications & Content, commercetools
Published 26 March 2021

Unless you are planning to give all products away for free, handling payments will be a crucial part of every eCommerce implementation. In order to make sure everything is done right, customers and brands using commercetools will use a Payment Service Provider (PSP) to handle the actual payment process. While PSPs make handling payments a lot easier, there still can be some challenges when integrating a PSP with commercetools.

build a robust payment integration with Adyen

Common challenges when integrating with a PSP

Different payment methods require different processes

There are plenty of payment methods in the world and each of them has different requirements. Even with a single payment method, there could be multiple processes that need to be covered and they’re constantly evolving. For example, consider credit cards. There are many card providers (e.g. Visa, MasterCard, American Express) and different card transaction protocols like 3-D Secure and 3-D Secure 2.0. And generally speaking, most merchants offer multiple payment methods, which means it will take a lot of development effort to properly implement and maintain all of them.

Correctly mapping payment status to order status

It is important to know when a payment is considered to be completed successfully because that means the order can be shipped. While this seems simple, there are lots of edge cases to consider here –what to do if the money is just reserved and not yet transferred, if the funds are still waiting for an action from the customer’s side? 

Usually, there are many more statuses that come from the payment provider and it is not always straightforward to interpret all these statuses and map them to the statuses supported by the shop.

Different devices require different payment flows

Nowadays, payment is done, not only on desktop computers and laptops, but also on tablets or mobile phones. Various devices typically require a different payment flow and, therefore, different UIs. It can be challenging to address the specific requirements of each of these devices to ensure a smooth user experience.

(Un)expected errors and frauds

When creating a payment system, it’s crucial to think of (and to prevent!) all kinds of unexpected situations and possible frauds. What should be the next step if the customer closes the browser tab before they can be successfully redirected to the shop? Should the shop allow the customer to return back from the payment page and add more products to the cart? What if the customer makes the payment in one browser tab, but at the same time they add more products in a different tab? These questions are not easy to answer and require experience to solve them properly.

How the new commercetools Adyen integration helps solve these challenges

Support for 50+ payment methods

The latest release of the integration has been rebuilt to support the Adyen web components out of the box. And the Adyen web components provide many payment methods instantly. Currently, it offers over 50 different payment methods. These cover card payments including 3-D Secure and 3-D Secure 2.0 authentication, PayPal or Sofort, as well as payment methods used locally like iDeal, Bancontact or Alipay. Additionally, new payment methods can be enabled with just a small change on the frontend – no backend changes required!

Secure server-to-server communication

Security is incredibly important when dealing with payment information. That is why the integration is designed to serve as a proxy between the commercetools platform and the Adyen API. It is built as an API extension, ensuring that communication with Adyen is done in the background every single time a payment is created or updated. The encrypted payment information, provided by the browser or even devices like the iOS or Android app, is passed along to the Adyen API directly. Not only does that make the integration completely touchpoint agnostic, it also removes complexity for developers, as they don’t need to learn and implement another API.

Automatic status handling

The integration also ensures that the payment statuses from Adyen are correctly mapped to the statuses in the payment objects in commercetools. It is enough to check the payment data in commercetools to know exactly when it is safe to ship the order.

Unified Commerce

commercetools is the leading headless, API-first commerce platform, which provides retailers with unprecedented agility and flexibility to build meaningful customer experiences. The integration combines commercetools with the powerful capabilities of Adyen, bringing Unified Commerce experiences regardless of device within reach for everyone.

Built and tested by the experts

Finally, it should be reassuring to know that the integration has been built as a collaboration between Adyen and commercetools to make sure it follows the best practices of both Adyen and commercetools. It has gone through extensive testing and quality checks to make sure it works seamlessly.

Getting started with the commercetools Adyen integration

The new version of the commercetools Adyen integration was released in early February. It is available through the commercetools Integration Marketplace. Like most integrations, it is provided as open source, enabling anyone to customize the integration to their needs.

Adding the integration to your environment

The integration was designed in such a way that it can run either on-premise or as a serverless function on AWS, Azure or GCP. The full integration consists of two standalone modules:

Extension module

The extension module is configured as a commercetools HTTP API extension. It handles checkout steps by intercepting payment modifications and executing communication with the Adyen API.

Notification module

The Notification module is a publicly exposed service that receives asynchronous notifications sent by Adyen. Through notifications, Adyen provides payment status changes like authorization, charge or refund of the payment asynchronously. The notification module will process the notification and update the matching commercetools payment accordingly.


The integration between Adyen and commercetools has become much more robust with this latest release. On top of that, it has gotten even easier to integrate into any environment, even for existing users of the integration. We are certain that this integration will help improve your customer experience by offering your shoppers their preferred local payment methods through one single solution for all sales channels; whether that is online, in app or in store.

Test the integration by signing up for the 60-day trial or reach out to us.

commercetools author image Stephanie Wittmann
Stephanie Wittmann
Head of Communications & Content, commercetools

Latest Blog Posts