Adyen

Adyen is a payment provider that lets merchants accept payments from customers worldwide. commercetools Frontend comes with an out-of-the-box integration with Adyen.

This document explains how to set up your e-commerce provider (for example, commercetools Composable Commerce) for the Adyen integration.

Furthermore, since the Adyen integration uses Adyen UI components, this document gives an overview of the Checkout Frontend component and of the payment webhook handler that comes built-in with the integration.

Prerequisites

An Adyen account
Adyen API credentials
A standard webhook set up in your Adyen Customer Area. You must register your payment notifications action handler as a webhook in the Adyen Customer Area to receive payment status updates.

Configure your e-commerce provider

To configure your e-commerce provider, follow these steps. While the following example uses commercetools Composable Commerce, you can adapt these instructions to your e-commerce provider.

Log in to the Merchant Center and go to Settings > Project settings.
From the International tab, set up the currencies, languages, and countries for your Composable Commerce Project.

The languages specified in the e-commerce provider must also be set in the project.yml file of your commercetools Frontend project under the languages key.

In the Zones pane, group the countries that share shipping costs.

From the Taxes tab, configure the Tax Categories and Tax Rates for your Composable Commerce Project.

From the Shipping methods tab, configure the Shipping Methods and shipping rates for your Composable Commerce Project.

Add Adyen credentials to your project configuration

In the project.yml file of your commercetools Frontend project, add your Adyen credentials in the configuration section as follows.

Add your Adyen credentialsyaml

## project settings
payment:
  adyen:
    apiKey: <replace-with-adyen-api-key>
    merchantAccount: <replace-with-adyen-mechant-account-code>
    clientKey: <replace-with-adyen-client-key>
    baseUrl: https://checkout-test.adyen.com/v69
    hmacKey: <replace-with-adyen-webhook-hmac>
## other configurations

The baseUrl used in the following example is for test accounts only. You must replace this baseUrl with the live endpoint before releasing the application, as described in Adyen documentation.

Checkout payment component

With the Adyen integration, you don't need to implement any Frontend component because the Checkout Frontend component (/packages/frontend/frontastic/tastics/checkout/index.tsx) uses the Adyen Web Drop-in component to handle the checkout flow.

The AdyenCheckout component (/packages/frontend/components/commercetools-ui/adyen-checkout/index.tsx) handles:

The selection of shipping and billing addresses.
The display of an order overview.
The listing of available payment methods.
The collection of payment credentials from users.

You can also edit this component to suit your business needs.

Payment webhook handler

The Adyen integration has a built-in webhook handler in the packages/backend/payment-adyen/actionControllers/AdyenController.ts file.

This webhook handles payment success notifications coming from Adyen by creating the https://<your-site>/frontastic/action/payment/notifications endpoint that you specified during the setup of the webhook in the Adyen Customer Area.

The webhook covers basic payment flow and order status update with the commerce provider. You can also edit the webhook function to handle your business-specific requirements, such as accepting partial payments.