Adyen

AdyenExternal link icon 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.

Information icon

Prerequisites

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.

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

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.

The International tab in the Project settings of the Merchant Center with the Currencies, Languages, and Countries panes and related sample settings.

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

The Zones pane in the International tab in the Project settings of the Merchant Center and related sample settings.

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

The Taxes tab in the Project settings of the Merchant Center and related sample settings.

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

The Shipping methods tab in the Project settings of the Merchant Center and related sample settings.

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
Clipboard icon
Information icon

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 documentationExternal link icon.

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 componentExternal link icon 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 AreaExternal link icon.

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.