Adyen integration

This guide explains how Front-Commerce allows using Adyen in a headless commerce project.

There are different ways for you to accept payments with Adyen in your Front-Commerce application.

As a Front-Commerce payment method

Since version 2.10.0

P.S. No Magento modules are needed if you use this method. If you however want to integrate with the Adyen Magento module please refer to Magento2 Integration section.

Add the required environment variables

• FRONT_COMMERCE_ADYEN_MERCHANT_ACCOUNT The merchant account name. You can find it in your Adyen Customer Area in the top left corner next to your company name
• FRONT_COMMERCE_ADYEN_CLIENT_KEY The environment variable which contains your Adyen client key for the domains of your Front-Commerce stores. You can find it in your Adyen Customer Area under Developers > API Credential > [your_prefered_credential] > Client Key > Client Key
• FRONT_COMMERCE_ADYEN_API_KEY The API key. You can find it in your Adyen Customer Area under Developers > API Credential > [your_prefered_credential] > API Key > API Key
• FRONT_COMMERCE_ADYEN_LIVE_URL_PREFIX only needed in production environment. Should be configured to contain the Adyen live URL prefix
• FRONT_COMMERCE_ADYEN_NOTIFICATION_USERNAME (more on webhooks below) you create it. You then have to copy it to the webhook section in your Adyen Customer Area under Developers > Webhooks > [your_prefered_webhook] > Authentication > User Name
• FRONT_COMMERCE_ADYEN_NOTIFICATION_PASSWORD (more on webhooks below) you create it. You then have to copy it to the webhook section in your Adyen Customer Area under Developers > Webhooks > [your_prefered_webhook] > Authentication > Password
• FRONT_COMMERCE_ADYEN_HMAC_KEY (more on webhooks below) create it from the webhook section in your Adyen Customer Area under Developers > Webhooks > [your_prefered_webhook] > Additional Settings > HMAC key
• FRONT_COMMERCE_ADYEN_PREVIOUS_HMAC_KEY (more on webhooks below) when you regenerate your HMAC key configure this to be the old one
• FRONT_COMMERCE_ADYEN_STORE_PAYMENT_DETAILS (optional) (more on Adyen's Stored Payment Methods). If you want to enable Adyen's Stored Payment Methods (Tokenization).

.env

FRONT_COMMERCE_ADYEN_MERCHANT_ACCOUNT=ExampleMerchant
FRONT_COMMERCE_ADYEN_CLIENT_KEY=live_32charactersstring
# the Adyen client key is prefixed with live_ or test_
FRONT_COMMERCE_ADYEN_API_KEY=a_very_very_very_long_key
FRONT_COMMERCE_ADYEN_LIVE_URL_PREFIX=1797a841fbb37ca7-AdyenDemo-
FRONT_COMMERCE_ADYEN_NOTIFICATION_USERNAME=a_username
FRONT_COMMERCE_ADYEN_NOTIFICATION_PASSWORD=a_password
FRONT_COMMERCE_ADYEN_HMAC_KEY=the_hmac_key
FRONT_COMMERCE_ADYEN_PREVIOUS_HMAC_KEY=the_previous_hmac_key
FRONT_COMMERCE_ADYEN_STORE_PAYMENT_DETAILS=true

Register the Adyen payment module in Front-Commerce

In your Front-Commerce application:

For Magento1 (OpenMage LTS):

.front-commerce.js

module.exports = {
  modules: ["./node_modules/front-commerce/modules/payment-adyen"],
  serverModules: [
    { name: "FrontCommerce", path: "server/modules/front-commerce" },
    { name: "Magento1", path: "server/modules/magento1" },
    {
      name: "Magento1Adyen",
      path: "payment-adyen/server/modules/payment-adyen",
    },
  ],
  webModules: [
    { name: "FrontCommerce", path: "front-commerce/src/web" },
    {
      name: "Adyen",
      path: "front-commerce/modules/payment-adyen/web",
    },
  ],
};

For Magento2:

.front-commerce.js

module.exports = {
  modules: ["./node_modules/front-commerce/modules/payment-adyen"],
  serverModules: [
    { name: "FrontCommerce", path: "server/modules/front-commerce" },
    { name: "Magento2", path: "server/modules/magento2" },
    {
      name: "Magento2Adyen",
      path: "payment-adyen/server/modules/payment-adyen/index.magento2.js",
    },
  ],
  webModules: [
    { name: "FrontCommerce", path: "front-commerce/src/web" },
    {
      name: "Adyen",
      path: "front-commerce/modules/payment-adyen/web",
    },
  ],
};

Register your Adyen payment components

note

This is a temporary way to setup payment components. We are aware that it is tedious. It will definitely change in the future, when Front-Commerce will support new extension points for Payments.

1. Override the file that lets you register additional payments forms in Front-Commerce

   mkdir -p my-module/web/theme/modules/Checkout/Payment/AdditionalPaymentInformation/
   cp -u node_modules/front-commerce/src/web/theme/modules/Checkout/Payment/AdditionalPaymentInformation/getAdditionalDataComponent.js my-module/web/theme/modules/Checkout/Payment/AdditionalPaymentInformation/getAdditionalDataComponent.js

2. Register Adyen

   my-module/web/theme/modules/Checkout/Payment/AdditionalPaymentInformation/getAdditionalDataComponent.js

   +import AdyenCheckout from "./AdyenCheckout";
   
   const ComponentMap = {};
   
   const getAdditionalDataComponent = (method) => {
   +  if (method.code.startsWith("adyen_")) {
   +    return AdyenCheckout;
   +  }
     return ComponentMap[method.code];
   };

3. Override the file that lets you register additional payments actions in Front-Commerce

   mkdir -p my-module/web/theme/modules/Checkout/PlaceOrder
   cp -u node_modules/front-commerce/src/web/theme/modules/Checkout/PlaceOrder/getAdditionalActionComponent.js my-module/web/theme/modules/Checkout/PlaceOrder/getAdditionalActionComponent.js

4. Register the Adyen action

   my-module/web/theme/modules/Checkout/PlaceOrder/getAdditionalActionComponent.js

   import None from "./AdditionalAction/None";
   +import Adyen from "./AdditionalAction/Adyen";
   
   const ComponentMap = {};
   
   const getAdditionalActionComponent = (paymentCode, paymentAdditionalData) => {
   +  if (paymentCode.startsWith("adyen")) {
   +    return Adyen;
   +  }
     return ComponentMap?.[paymentCode] ?? None;
   };

5. register custom Flash message components to display payment messages in an optimized way (recommended)

   mkdir -p my-module/web/theme/modules/FlashMessages
   cp -u node_modules/front-commerce/src/web/theme/modules/FlashMessages/getFlashMessageComponent.js my-module/web/theme/modules/FlashMessages/getFlashMessageComponent.js
   my-module/web/theme/modules/FlashMessages/getFlashMessageComponent.js

   import React from "react";
   import {
     InfoAlert,
     ErrorAlert,
     SuccessAlert,
   } from "theme/components/molecules/Alert";
   import { BodyParagraph } from "theme/components/atoms/Typography/Body";
   + import {
   +   AdyenPaymentSuccess,
   +   AdyenPaymentError,
   + } from "theme/modules/Adyen/FlashMessage";
   
   // […]
   const ComponentMap = {
     default: makeAlertMessageComponent(InfoAlert),
     info: makeAlertMessageComponent(InfoAlert),
     error: makeAlertMessageComponent(ErrorAlert),
     success: makeAlertMessageComponent(SuccessAlert),
   +  adyenSuccess: AdyenPaymentSuccess,
   +  adyenError: AdyenPaymentError,
   };

Update your CSPs

To allow loading Adyen related remote resources:

my-module/config/website.js

  contentSecurityPolicy: {
    directives: {
      scriptSrc: [],
-      frameSrc: [],
+      frameSrc: ["*.adyen.com", "*"], // only for FC < 2.19, allowing all is required
+      frameSrc: ["*.adyen.com"], // since FC 2.19
      styleSrc: [],
-      imgSrc: [],
+      imgSrc: ["*.adyen.com"],
-      connectSrc: [],
+      connectSrc: ["*.adyen.com"],
      baseUri: []
    },
    // since FC 2.19
+    reportOnlyDirectives: {
+      frameSrc: true,
+    }
  },

Loose CSP on iframes

The reportOnlyDirectives block allows all iframes on you application, this is required to allow 3DS2 authentication iframes to load in your site.

If you are not using the credit card payments consider removing this code block (for FC < 2.19, please remove the "*" rule instead).

Register custom styles (optional)

Developers can customize Adyen drop-in UI styles using CSS.

You can add an optional stylesheet from Front-Commerce in your application to customize styles. The provided stylesheet reuses existing styles from the theme as much as possible for a good integration by default. You can override it if needed to adapt the UI as wanted.

Add the following line to your web/theme/modules/_modules.scss file to load these styles:

@import "~theme/modules/Adyen/dropinCustomizations";

Add webhook

In your Adyen Customer Area under Developers > Webhooks click on the + Webkook button on the right top corner then click on Add for the Standard Notification type. Fill the fields as follows:

• Transport:
  • URL: the full url of your site followed by /webhooks/payment/notification/adyen e.g. https://www.example.com/webhooks/payment/notification/adyen
  • Method: JSON
• Authentication:
  • User Name: the FRONT_COMMERCE_ADYEN_NOTIFICATION_USERNAME environment variable defined above
  • Password: the FRONT_COMMERCE_ADYEN_NOTIFICATION_PASSWORD environment variable defined above
• Additional Settings
  • HMAC Key (HEX Encoded): click generate and copy it to FRONT_COMMERCE_ADYEN_HMAC_KEY environment variable defined above

Enable Paypal payments

To enable PayPal payments, you need to:

• add PayPal payment method in your Adyen account
• update your CSPs with the ones from PayPal.

Enable Adyen's Stored Payment Methods (optional)

You can opt for Adyen to store your customers' credit card information and allow a faster checkout experience by adding FRONT_COMMERCE_ADYEN_STORE_PAYMENT_DETAILS=true in your .env file.

If you are using the default Front-Commerce Adyen component, your customer should now be able to save their credit card information during checkout by checking the "Save for my next payment" checkbox.

Enable Google Pay payments

To enable Google Pay payments, you need to:

• add Google Pay payment method in your Adyen account
• Update your CSPs:

my-module/config/website.js

  contentSecurityPolicy: {
    directives: {
-     scriptSrc: [],
+     scriptSrc: ["pay.google.com"],
-     frameSrc: [],
+     frameSrc: ["pay.google.com"],
      styleSrc: [],
      imgSrc: [],
      connectSrc: [],
      baseUri: []
    }
  },

That's it!

You can now configure your Adyen payment methods from the Customer Area under Settings > Payment Methods and test the integration

note

Please keep in mind that Adyen payment methods depend on the Customer's country, the Cart amount, and the Store currency. Different contexts could display different payment methods in the checkout.

As a Magento2 Integration

Since version 2.3.0 (developer preview since 2.1.0)

note

This integration aims to be transparent for administrators and developers. That is why we haven't duplicated documentation from existing Magento resources. Please contact us if you need further assistance.

Front-Commerce is compatible with Adyen's official Magento headless integration in its native version.

This integration is slightly different from traditional Magento2 headless payments in the sense that it contains a "companion component" in Front-Commerce. The component allows to display and Authorize payments from the checkout page, using Adyen's Web Drop-in integration on the front-end. No redirection to other payment platforms is involved unless it is absolutely necessary, the customer remains on the Front-Commerce store.

Here is how to set this payment method up.

Install and configure the Adyen_Payment Magento2 extension (7.2+ < 9.0)

Follow Adyen's documentation to install and configure the official Magento2 extension for Adyen payments. We currently support any version from 7.2.0 to 8.x.

tip

If you were using Adyen with Magento2 without Front-Commerce, don't forget to check Adyen settings. For instance, make sure allowed origins set the step 1 match you setup with Front-Commerce.

You must configure the extension's Headless/PWA settings with your Front-Commerce URL for each of your stores. Settings changed in version 8.0.0, so it will be slightly different depending on your version.

• < 8: configure "Payment Origin URL" in the Advanced: PWA section
• >= 8: configure Advanced settings > Headless Integration with
  • Payment Origin URL: your Front-Commerce URL (e.g: http://localhost:4000/)
  • Payment Return URL: the /adyen/process/result path (e.g: http://localhost:4000/adyen/process/result)
  • Custom Success Redirect Path: same value as Payment Return URL

important

Please note that enabling or disabling payments in Magento's admin area has no effect on payment methods visible on the storefront. This is a feature of the module: every active payment method in Adyen will be available. You either have to filter them in the frontend or from your Adyen account.

Add the required environment variables

• FRONT_COMMERCE_ADYEN_CLIENT_KEY The environment variable which contains your Adyen client key for the domains of your Front-Commerce stores. You can find it in your Adyen Customer Area under Developers > API Credential > [your_prefered_credential] > Client Key > Client Key
• FRONT_COMMERCE_ADYEN_MAGENTO_MODULE_VERSION The version of the Magento2 Adyen module you use. You can find it in your magento backend, under Stores > Configuration > Sales > Payment Methods > Adyen Payments > Documentation and Support.
• FRONT_COMMERCE_ADYEN_STORE_PAYMENT_DETAILS (optional) (more on Adyen's Stored Payment Methods). If you want to enable Adyen's Stored Payment Methods (Tokenization).

.env

FRONT_COMMERCE_ADYEN_CLIENT_KEY=live_32charactersstring
# the Adyen client key is prefixed with live_ or test_
FRONT_COMMERCE_ADYEN_MAGENTO_MODULE_VERSION=8.3.3
FRONT_COMMERCE_ADYEN_STORE_PAYMENT_DETAILS=true

Register the Adyen payment module in Front-Commerce

.front-commerce.js

-  modules: [],
+  modules: ["./node_modules/front-commerce/modules/payment-adyen"],
   serverModules: [
     { name: "FrontCommerce", path: "server/modules/front-commerce" },
-    { name: "Magento2", path: "server/modules/magento2" }
+    { name: "Magento2", path: "server/modules/magento2" },
+    {
+      name: "Magento2Adyen",
+      path: "payment-adyen/server/modules/magento2-payment-adyen",
+    }
   ],
   webModules: [
-    { name: "FrontCommerce", path: "front-commerce/src/web" }
+    { name: "FrontCommerce", path: "front-commerce/src/web" },
+    {
+      name: "Magento2Adyen",
+      path: "front-commerce/modules/payment-adyen/web",
+    }
   ]

Register your Adyen payment components

Same as above

Update your CSPs

Same as above

Register custom styles (optional)

Same as above

Enable Adyen's Stored Payment Methods (optional)

You can opt for Adyen to store your customers' credit card information to allow a faster checkout experience.

In order to do so:

• Add FRONT_COMMERCE_ADYEN_STORE_PAYMENT_DETAILS=true in your .env file
• Follow Adyen's guide on how to setup tokenization using Adyen's Magento module.

If you are using the default Front-Commerce Adyen component, your customer should now be able to save their credit card information during checkout by checking the "Save for my next payment" checkbox.

Enable Paypal payments

To enable PayPal payments, you need to:

• add PayPal payment method in your Adyen account
• enable Adyen's Alternative Payment Methods in your Magento2 backend, located in Stores > Configuration > Sales > Payment Methods > Adyen Payments > Configure payment methods
• update your CSPs with the ones from PayPal.

Enable Google Pay payments

To enable Google Pay payments, you need to:

• add Google Pay payment method in your Adyen account
• Update your CSPs:

my-module/config/website.js

  contentSecurityPolicy: {
    directives: {
-     scriptSrc: [],
+     scriptSrc: ["pay.google.com"],
-     frameSrc: [],
+     frameSrc: ["pay.google.com"],
      styleSrc: [],
      imgSrc: [],
      connectSrc: [],
      baseUri: []
    }
  },

That's it!

You can now configure the Magento extension to use a Test mode and test the integration

note

Please keep in mind that Adyen payment methods depends on the Customer country, the Cart amount and the Store currency. Different contexts could display different payment methods in the checkout.

Payment methods support

The following payment methods have been tested:

• Credit card
• Paypal
• Klarna (Pay now, Pay over time, Pay later)
• Google Pay
• Apple Pay (only shown when using Safari on an Apple device)
• Sofort
• Alipay Magento 2 module
• iDeal