Alokai Storefront configuration

This guide will show you how to configure Adyen integration for SFCC in a Alokai Storefront application.

Something's missing?

If you don't have an Alokai Storefront project yet, request a demo from our Sales team.

Requirements

SFCC sandbox environment with the latest version of the Adyen integration cartridge installed,
Alokai Storefront project with the SFCC integration installed,
@vsf-enterprise NPM registry access.

Install Server Middleware dependencies

Navigate to the Server Middleware directory:

cd apps/storefront-middleware

and install the following packages

yarn add @vsf-enterprise/adyen-sfcc-api

Install Storefront dependencies

Navigate to the Storefront directory:

cd apps/storefront-unified-nextjs

and install the following packages

yarn add @vsf-enterprise/adyen-sfcc-sdk

Configure Server Middleware

To register the Adyen integration in the Server Middleware, add its credentials to the .env file in the /apps/storefront-middleware directory:

.env

ADYEN_API_KEY=<ADYEN_API_KEY>
ADYEN_MERCHANT_ACCOUNT=<ADYEN_MERCHANT_ACCOUNT>
ADYEN_CHECKOUT_API_BASE_URL=<ADYEN_CHECKOUT_API_BASE_URL>
ADYEN_ENVIRONMENT=<ADYEN_ENVIRONMENT>
SFCC_API_MIDDLEWARE_NAME=<SFCC_API_MIDDLEWARE_NAME>
ADYEN_PAYMENT_METHOD_ID=<ADYEN_PAYMENT_METHOD_ID>
ADYEN_CHECKOUT_API_VERSION=<ADYEN_CHECKOUT_API_VERSION>

and use them in the middleware.config.ts file located in the same directory.

middleware.config.ts

import type { Basket } from "@vsf-enterprise/sfcc-types";
import type { OrderPaymentInstrument } from "@vsf-enterprise/adyen-sfcc-types";

const {
  ADYEN_API_KEY,
  ADYEN_MERCHANT_ACCOUNT,
  ADYEN_CHECKOUT_API_BASE_URL,
  ADYEN_ENVIRONMENT,
  SFCC_API_MIDDLEWARE_NAME,
  ADYEN_PAYMENT_METHOD_ID,
  ADYEN_CHECKOUT_API_VERSION
} = process.env;

export default {
  integrations: {
    // ...
    adyen: {
      location: "@vsf-enterprise/adyen-sfcc-api/server",
      configuration: {
        adyenApiKey: ADYEN_API_KEY,
        adyenMerchantAccount: ADYEN_MERCHANT_ACCOUNT,
        adyenCheckoutApiBaseUrl: ADYEN_CHECKOUT_API_BASE_URL,
        returnUrl: (cart: Basket, payment: OrderPaymentInstrument) => '<ADYEN_RETURN_URL>',
        environment: ADYEN_ENVIRONMENT,
        sfccApiMiddlewareName: SFCC_API_MIDDLEWARE_NAME,
        adyenPaymentMethodId: ADYEN_PAYMENT_METHOD_ID,
        adyenCheckoutApiVersion: ADYEN_CHECKOUT_API_VERSION,
        buildCustomPaymentAttributes: (params) => {},
        buildCustomSessionAttributes: (params) => {},
      }
    }
  },
};

A complete list describing available configuration options can be found below.

Property	Required?	Description
adyenApiKey	✅	Your Adyen API Key
adyenMerchantAccount	✅	Name of your Adyen Merchant Account
adyenCheckoutApiBaseUrl	✅	One of Adyen Checkout Endpoints. `[version]` and `[method]` can be skipped.
returnUrl	✅	The url used to initialize the session call and for 3rd party payment providers to redirect to after processing a payment. Either a string (e.g. http://localhost:3000/adyen/return) or a function (with access to `cart` and `payment`) returning a string.
environment	✅	Type of your Adyen environment (e.g. TESt or LIVE)
sfccApiMiddlewareName	✅	The key used to register SFCC integration in middleware.config.ts. Usually commerce or sfcc. Required for orchestration purposes.
adyenPaymentMethodId	❌	The name of the Payment Method added to SFCC by Adyen's cartridge. Defaults to AdyenComponent
adyenCheckoutApiVersion	❌	Adyen Checkout API Version
buildCustomSessionAttributes	❌	Function returning object that will be assigned to the payload sent to the Adyen's POST /sessions endpoint
buildCustomPaymentAttributes	❌	Function returning object that will be assigned to the payload sent to the Adyen's POST /payments endpoint

Configure SDK

The next step is adding Adyen module to Alokai SDK.

In the /apps/storefront-unified-nextjs/sdk directory, find the sdk.config.ts file and initialize the Adyen module with the following lines:

sdk.config.ts

import { adyenSFCCModule, AdyenSFCCModuleType } from '@vsf-enterprise/adyen-sfcc-sdk';

export const { getSdk } = createSdk(options, ({ buildModule, middlewareUrl, getRequestHeaders }) => ({
  // ...other modules
  adyen: buildModule<AdyenSFCCModuleType>(adyenSFCCModule, {
    apiUrl: `${middlewareUrl}/adyen`,
    adyenClientKey: '<ADYEN_CLIENT_KEY>',
    adyenEnvironment: '<ENVIRONMENT>',
  }),
}));

Property	Required?	Description
apiUrl	✅	The base URL of the Adyen integration registered in the Server Middleware
adyenClientKey	✅	Your Adyen Client Key
adyenEnvironment	✅	Type of your Adyen environment (e.g. test or live)

What next?

With your Alokai Storefront project configured, proceed to the Guides section of our documentation. Start by learning how to place your first order.

Placing your first order

Place your first order in SFCC and accept your first payment using Adyen

Payment methods guide

Learn how to support a wide range of payment methods

Extend payment request guide

Learn how to send custom attributes to Adyen

Payment retry guide

Enabling payment retries in both on-site and redirect-based flows