Plugins-2 icon

Install and set up the package

Install and set up the Adyen Composable Storefront package.

Start integrating with Salesforce Composable Storefront package

Choose your version
2.0.1

Requirements

Visit the Adyen Salesforce Headless Commerce PWA repository on GitHub to see an example integration with the Adyen package.

Before you begin, make sure that:

  1. You have installed the supported Node and npm versions.
  2. You have a Salesforce sandbox connected to your Salesforce Commerce Cloud (SFCC) instance.
  3. You have set up your environments, sites, locales and currencies, and product inventories.
  4. You have reached out to your Salesforce account team and enabled Managed Runtime (MRT) on your SFCC instance.
  5. Your have set your MRT permissions to Admin.
  6. You have understood the configuration file structure of the Salesforce PWA kit.

The Adyen npm package can be integrated into the default Salesforce Retail React App or into your Custom Retail React App.

Step 1: Build your local PWA app

To use Adyen as the payment processor for your PWA app, you need to generate a new PWA project.

  1. Initiate the Salesforce PWA Kit starter project with the following command:

    Expand view
    Copy link to code block
    Copy code
    Copy code
    npx @salesforce/pwa-kit-create-app

    The command-line interface guides you through the setup. While you set up your project, you are asked to link the generated retail app to a demo sandbox or your own sandbox.

  2. Only if you link the retail app to your own sandbox, enter the following details at the command prompt when creating the new app:
  3. Launch your retail app with the following command:
    Expand view
    Copy link to code block
    Copy code
    Copy code
    npm run start

Step 2: Install the Adyen package in your local PWA app

  1. In the root directory of your PWA app, install the Adyen Salesforce PWA npm package:

    Expand view
    Copy link to code block
    Copy code
    Copy code
    npm install @adyen/adyen-salesforce-pwa
  2. In your PWA app, adjust the overrides/app/ssr.js file to import Adyen routes. You must import routes in the following order:

    1. Adyen routes. Add the following line:

      Expand view
      Copy link to code block
      Copy code
      Copy code
      import {registerAdyenEndpoints} from '@adyen/adyen-salesforce-pwa/dist/ssr/index.js'
    2. Default Salesforce routes.

    3. Custom routes. We recommend you integrate and test the package without customizations first.

  3. In the overrides/app folder of your Retail React app:

    1. In routes.jsx, import the Adyen CSS file:

      Expand view
      Copy link to code block
      Copy code
      Copy code
      import '@adyen/adyen-salesforce-pwa/dist/app/adyen.css'
    2. Override the checkout/index.jsx file to wrap the Salesforce checkout provider with the Adyen checkout provider, passing the relevant hooks.

      Expand view
      Copy link to code block
      Copy code
      Copy code
      import Payment from './partials/payment'
      import {AdyenCheckoutProvider} from '@adyen/adyen-salesforce-pwa'
      import '@adyen/adyen-salesforce-pwa/dist/app/adyen.css'
      import {
      useAccessToken,
      useCustomerId,
      useCustomerType,
      useShopperBasketsMutation
      } from '@salesforce/commerce-sdk-react'
      import useMultiSite from '@salesforce/retail-react-app/app/hooks/use-multi-site'
      import useNavigation from '@salesforce/retail-react-app/app/hooks/use-navigation'

      See the file in our example package in GitHub.

    3. Override the checkout/partials/payment.jsx file to render the AdyenCheckout component from the adyen-salesforce-pwa package. See how you can render the component in our GitHub.

    4. Override the checkout/confirmation.jsx file to wrap the Salesforce checkout confirmation page with the AdyenCheckout and AdyenCheckoutProvider from the adyen-salesforce-pwa package. See how you can render the components in our GitHub.

    5. Create an error page and register it in routes.jsx as checkout/error. See the example error page in our GitHub.

    6. Create a redirect page and register it in routes.jsx as checkout/redirect. See the example redirect page in our GitHub.

    See the routes.jsxfile on our GitHub to see how you can register pages.

  4. In your package.json file, add the following scripts:

    Expand view
    Copy link to code block
    Copy code
    Copy code
    "upload-env": "upload-env",
    "get-env": "get-env",
    "start:env": "include-env -p=npm run start",
    "push:env": "include-env -p=npm run push"
  5. Run the integration:

    Expand view
    Copy link to code block
    Copy code
    Copy code
    npm run start :env

Step 3: Set up locales in your PWA app

The config/default.js file in the PWA Retail React app contains the locale definitions for your sites. You need to update this file with the locales you want to support in your Salesforce Commerce Cloud site:

  1. In the PWA Retail React app package, go to the config/default.js file.

  2. Set the following fields:

    Field Description
    supportedCurrencies The array of all currencies for the locales you have set up.
    defaultCurrency The default currency for your site.
    defaultLocale The default locale for your site.
    supportedLocales The array for all locale objects. Each locale object consists of:
    • id: the locale ID, for example en-US.
    • preferredCurrency: the currency for the locale, for example: USD.
    • alias (optional): You can use this attribute if you want to use other string instead of the id.

    See the PWA integration with the Adyen package on GitHub to see an example locale configuration.

  3. In the config/default.js file, change the local attribute from none to query_param or path to display the locale in the URL.

  4. Only if you defined the alias field for locales, in the config/default.js file, remove the comment markers for siteAliases, and provide the aliases for your sites.

Step 4: Generate an Adyen API Key

If you already have an SFCC integration with Adyen using Store Front Reference Architecture (SFRA) or SiteGenesis, you do not have to generate a new API Key and you can skip this step.

To connect your PWA store to the Adyen APIs, you need to generate an API key in your Adyen Customer Area and add it to the package configuration when you set environment variables in a later step.

  1. Log in to your Customer Area.
  2. Go to Developers > API credentials, and select the API credential username for your integration, for example ws@Company.[YourCompanyAccount].
  3. Under Server settings > Authentication select the API key tab.
  4. Select Generate API key.
  5. Select the copy icon and store your API key securely in your system.
  6. Select Save changes.

Step 5: Set up webhooks in the Adyen Customer Area

Adyen uses webhooks to inform your Salesforce Commerce Cloud store of payment status changes.

To set up webhooks:

  1. In your Customer Area, go to Developers >  Webhooks. If you want to configure webhooks for a merchant account, switch to that merchant account.

  2. Select Webhook.

  3. From the list of webhooks, next to Standard webhook, select Add.

  4. Under General, configure the following:

    Setting Description
    Enabled Select the toggle to enable or disable the webhook.
    Version The webhook version.
    Description Your description of the webhook.
  5. Under Server configuration, configure the following:

    Setting Description
    URL Your website URL followed by /api/adyen/webhook.
    Method JSON
    Encryption protocol TLSv1.3
  6. Under Security, configure the following:

    Setting Description
    Basic authentication Enter your server's username and password. You need to enter these credentials when setting environment variables later.
    HMAC Key Generate the HMAC Key, copy it, and store it securely in your system. You need to enter the key when setting environment variables later.
    Learn more about verifying HMAC signatures.
  7. Under Events settings, select the checkbox for the OFFER_CLOSED event code.

  8. If the Additional settings section is available, optionally select the additional information you want to receive in this webhook. Some webhook types do not support more than one event code, so this section does not appear.

  9. Select Save configuration.

The package implements the AUTHORISATION webhook by default. If you want to receive webhooks for more payment events, you can customize your integration after you have successfully deployed your application in MRT and completed testing without any customizations.

You cannot test Adyen webhooks on localhost.

Step 6: Deploy your application in Managed Runtime

Salesforce's Managed Runtime (MRT) provides the infrastructure to deploy, host, and monitor your PWA Kit application.

Managed Runtime only supports applications created from a PWA Kit template and has a separate admin dashboard. Before you can use MRT and Runtime Admin, Salesforce must enable it for your organization. To enable MRT and Runtime Admin for your organization, reach out to your Salesforce account team.

When building your storefront, keep the constraints of MRT environments in mind.

1. Create a new project in Managed Runtime

Follow the steps to create a project in Runtime Admin. Use the following details for your project:

Field Value
Project Name adyen-salesforce-headless-commerce-pwa
Project ID Project IDs must match the package name in the package.json file and can not be longer than 20 characters.
Scopes The list of scopes that are used to fetch baskets and create orders.

2. Set up the MRT environment

Set up an environment to separate your production storefront from other storefronts, such as development or testing storefronts. Refer to environments in Salesforce docs to learn more about environments.

  • Follow the steps to create an environment in Salesforce Docs.
    Name: use your Sandbox Org ID to easily identify an environment that belongs to a sandbox, and to create variables correctly for each environment.
    Region: we recommend to set your MRT region to the same region that your Salesforce sandbox uses.

    Your Composable Storefront integration with Adyen can only have one region connected to one MRT organization, one SFCC site, and one Adyen Customer Area account.

3. Set the environment variables

  1. In your MRT environment, navigate to your project by selecting your Organization and Project.
  2. Select Environment Variables.
  3. Specify the values for the following variables:

    When a variable contains YOUR_SITE_ID, replace it with your the same value as your Commerce API site ID.

    Variable Required Description
    YOUR_SITE_ID_ADYEN_API_KEY -white_check_mark- Your Adyen API key.
    YOUR_SITE_ID_ADYEN_MERCHANT_ACCOUNT -white_check_mark- Your Adyen merchant account name.
    YOUR_SITE_ID_ADYEN_CLIENT_KEY -white_check_mark- Your Adyen client key.
    YOUR_SITE_ID_ADYEN_ENVIRONMENT -white_check_mark- Use TEST. When you are ready to accept live payments, change the value to LIVE.
    YOUR_SITE_ID_ADYEN_WEBHOOK_USER -white_check_mark- The basic authentication username you entered when you set up webhooks.
    YOUR_SITE_ID_ADYEN_WEBHOOK_PASSWORD -white_check_mark- The basic authentication password you entered when you set up webhooks.
    YOUR_SITE_ID_ADYEN_HMAC_KEY -white_check_mark- The HMAC key you generated when you set up webhooks.
    YOUR_SITE_ID_ADYEN_LIVE_URL_PREFIX Only for Live
    environment
    Your live URL prefix to process live transactions.
    YOUR_SITE_ID_ADYEN_APPLE_DOMAIN_ASSOCIATION Only if you want to offer Apple Pay as a payment method in the live environment, set to the domain association file value.
    YOUR_SITE_ID_SYSTEM_INTEGRATOR_NAME The name of your system integrator.
    COMMERCE_API_CLIENT_ID -white_check_mark- Your MRT Commerce API client ID.
    COMMERCE_API_ORG_ID -white_check_mark- Your MRT Commerce API Org ID.
    COMMERCE_API_SHORT_CODE -white_check_mark- Your MRT Commerce API short code.
    COMMERCE_API_SITE_ID -white_check_mark- Your Salesforce site ID, for example, RefArch.
    COMMERCE_API_DEFAULT_SITE -white_check_mark- Your default Salesforce site, for example, RefArch.
    SCAPI_URL -white_check_mark- Your Salesforce Commerce API URL. Refer to Salesforce documentation for more information.
    OCAPI_URL -white_check_mark- Your Open Commerce API Url. Refer to Salesforce documentation for more information.
    ENVIRONMENT_ID -white_check_mark- Your MRT environment ID.
    PROJECT_ID -white_check_mark- Your project ID, for example, adyen-salesforce-pwa.
    COMMERCE_API_CLIENT_ID_PRIVATE -white_check_mark- Your Salesforce Commerce API client ID. To get your API credentials, create an API client in Salesforce.
    COMMERCE_API_CLIENT_SECRET -white_check_mark- Your Commerce API client secret for your Salesforce API client.
    SFCC_REALM_ID -white_check_mark- Your SFCC realm ID.
    SFCC_INSTANCE_ID -white_check_mark- Your SFCC instance ID.
    SFCC_OAUTH_SCOPES -white_check_mark- Your SFCC oauth scopes, for example, sfcc.orders sfcc.orders.rw. You also need to add this in your Salesforce Account Manager > API Client > OpenID Connect > Allowed Scopes. Refer to Salesforce documentation to learn more about authorization scopes.

    When going live, you need to update some variables you have entered with values from your live Customer Area.

4. Deploy your project to MRT

To run your application, you must deploy your application to MRT and to the environment you have set up. You also need a Personal MRT API Key.

  1. Follow the steps to generate a Personal MRT API key in Salesforce Docs.

  2. In your Retail React App, save your credentials:

    Expand view
    Copy link to code block
    Copy code
    Copy code
    npm run save-credentials -- --user YOUR_EMAIL --key YOUR_PERSONAL_MRT_API_KEY
  3. Push your build to MRT:

    Expand view
    Copy link to code block
    Copy code
    Copy code
    npm run push:env
  4. Follow the steps to deploy the bundle in Salesforce Docs to the environment you have created.

Step 7 (Optional): Import the Adyen country/region list

Salesforce allows you to add your list of countries/regions for shipping. Optionally, you can use our default list.

To use our country/region list, in your PWA Retail React app, import the Adyen countrylist and export it as SHIPPING_COUNTRY_CODES in the constants.js file:

Expand view
Copy link to code block
Copy code
Copy code
import {countryList} from '@adyen/adyen-salesforce-pwa'
export const SHIPPING_COUNTRY_CODES = countryList

Step 8: Migrate pages

If you already have an SFCC integration with Adyen using Store Front Reference Architecture (SFRA) or SiteGenesis, you need to migrate your store pages. If you do not have an SFCC integration with Adyen already, you can skip this step and start testing.

You can perform Phased Headless Rollouts to migrate your SFRA or SiteGenesis pages in a phased approach.

The Adyen package uses version 3.x of the Retail React App with template extensibility. To filter out links to non-PWA kit pages, you can override the overrides/app/routes.jsx file. Salesforce has sample code on GitHub that shows how to override.

If you are migrating the checkout page last, you need to route traffic to your SFRA checkout page from your PWA integration. To learn how to apply routing, refer to Salesforce Docs.

Test your integration

After you have installed and configured the package, use our test cards to test payments.

Check the status of test payments in your Customer Area > Transactions > Payments.