This is the early access documentation preview for Custom Views. This documentation might not be in sync with our official documentation.

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) and to configure the Adyen backend extension.

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

If the payment-adyen extension is not available in your commercetools Frontend project at this path packages/PROJECT_NAME/backend, before proceeding with the following configurations, you must:

  1. Clone the extension repository and add the code to your project.
  2. Register the extension in your project.

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 the currencies, languages, and countries for your Composable Commerce Project.

In your e-commerce provider, you must set the same languages as those set for the configuration of your commercetools Frontend project.

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.

Configure the Adyen extension

To configure the Adyen extension, follow these steps:

  1. Add the following project configuration fields to the project schema from the Studio.

    Add Adyen project configuration fieldsjson
    {
    "name": "Adyen Extension",
    "fields": [
    {
    "label": "Base URL",
    "field": "EXTENSION_ADYEN_BASE_URL",
    "type": "string",
    "translatable": false,
    "required": true
    },
    {
    "label": "Merchant Account",
    "field": "EXTENSION_ADYEN_MERCHANT_ACCOUNT",
    "type": "string",
    "translatable": false,
    "required": true
    },
    {
    "label": "API Key",
    "field": "EXTENSION_ADYEN_API_KEY",
    "type": "encrypted",
    "translatable": false,
    "required": true
    },
    {
    "label": "Password",
    "field": "EXTENSION_ADYEN_PASSWORD",
    "type": "encrypted",
    "translatable": false,
    "required": true
    },
    {
    "label": "HMAC Key",
    "field": "EXTENSION_ADYEN_HMAC_KEY",
    "type": "encrypted",
    "translatable": false,
    "required": true
    }
    ]
    }
  2. Set the Adyen configuration values from the Studio.

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.