Install and set up the package

Before you begin

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.

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:

   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, input the following details in the command prompt when creating the new app:
   • Sandbox URL
   • Shopper Login and API Access Service (SLAS) client ID
   • Site (storefront) ID
   • Organization (Org) ID
   • Short code
3. Launch your retail app with the following command:

   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:

   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:

      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:
   1. In routes.jsx, import the Adyen CSS file:

      import '@adyen/adyen-salesforce-pwa/dist/app/adyen.css'

   2. Override the checkout/index.jsx file into your Retail React app and wrap the Salesforce checkout provider with the Adyen checkout provider, passing the relevant hooks.
      See the file in our example package on 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 on our GitHub.
   4. Create an error page and a redirect and register them in routes.jsx:
      • Register the error page as checkout/error. See the example error page.
      • Register the redirect page as checkout/redirect. See the example redirect page.
        See the routes.jsxfile on our GitHub to see how you can register pages.
4. In your package.json file, add the following scripts:

   "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:

   npm run start :env

Step 3: Set up locales in your PWA app

The config/sites.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/sites.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/sites.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/sites.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 payment methods

Add supported payments methods that you want to offer to your shoppers, in your Adyen Customer Area.

Then, enable Adyen as the payment processor for cards and other local payment methods that you have added, in Salesforce:

1. In the Salesforce Business Manager, go to Merchant tools > Ordering > Payment Methods.
2. In the Payment Methods overview, check the ID column to make sure that AdyenComponent and CREDIT_CARD are enabled.
3. Under Details, set Payment Processor to Adyen_Component for both types.

Step 6: 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. Log in to your Customer Area. If you want to configure webhooks for a merchant account, switch to that merchant account.

2. Go to Developers > Webhooks.

3. Select Webhook.

4. In the row for the Standard webhook, select Add.

5. Configure General settings:

   Setting	Description
   Server configuration	URL: Your website URL followed by /adyen/webhook. Method: JSON. Encryption Protocol: TLSv.1.3.
   Merchant accounts	Select which merchant accounts this webhook is for.
   Events	Select the checkbox for the OFFER_CLOSED event code.

6. Configure Security settings:

   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. Select Save changes.

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.

Step 7: 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:

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. Create an .env file in your Retail React App by doing either of the following:

   • Copy the .env.example file from the PWA integration with the Adyen package on GitHub and rename the file to .env.
   • Create a new .env file.

2. Set the variables in the .env file. Replace YOUR_SITE_ID in the variables with your Salesforce Site ID, this value is identical to the value you have for COMMERCE_API_SITE_ID.

   YOUR_SITE_ID_ADYEN_API_KEY="YOUR_ADYEN_API_KEY"
   YOUR_SITE_ID_ADYEN_MERCHANT_ACCOUNT="YOUR_ADYEN_MERCHANT_ACCOUNT"
   YOUR_SITE_ID_ADYEN_CLIENT_KEY="YOUR_ADYEN_CLIENT_KEY"
   YOUR_SITE_ID_SYSTEM_INTEGRATOR_NAME="YOUR_SYSTEM_INTEGRATOR_COMPANY_NAME"
   YOUR_SITE_ID_ADYEN_ENVIRONMENT="TEST" // switch to
   YOUR_SITE_ID_ADYEN_WEBHOOK_USER="YOUR_ADYEN_WEBHOOK_USERNAME"
   YOUR_SITE_ID_ADYEN_WEBHOOK_PASSWORD="YOUR_ADYEN_WEBHOOK_PASSWORD"
   YOUR_SITE_ID_ADYEN_HMAC_KEY="YOUR_ADYEN_HMAC_KEY"
   HOST_URL="http://localhost:3000"
   COMMERCE_API_CLIENT_ID="YOUR_MRT_COMMERCE_API_CLIENT_ID"
   COMMERCE_API_ORG_ID="YOUR_MRT_COMMERCE_API_ORG_ID"
   COMMERCE_API_SHORT_CODE="YOUR_MRT_COMMERCE_API_SHORT_CODE"
   COMMERCE_API_SITE_ID="RefArch"
   COMMERCE_API_DEFAULT_SITE="RefArch"
   SCAPI_URL="*.api.commercecloud.salesforce.com"
   OCAPI_URL="*-123.sandbox.xx00.dx.commercecloud.salesforce.com"
   ENVIRONMENT_ID="YOUR_MRT_ENVIRONMENT_ID"
   PROJECT_ID="adyen-salesforce-pwa"
   COMMERCE_API_CLIENT_ID_PRIVATE="YOUR_COMMERCE_API_CLIENT_ID"
   COMMERCE_API_CLIENT_SECRET="YOUR_COMMERCE_API_CLIENT_SECRET"
   SFCC_REALM_ID="YOUR_SFCC_REALM_ID"
   SFCC_INSTANCE_ID="YOUR_SFCC_INSTANCE_ID"
   SFCC_OAUTH_SCOPES="sfcc.orders sfcc.orders.rw"

   To obtain your Commerce API client ID and the client secret, create an API client in Salesforce.

   • You need to add your SFCC_OAUTH_SCOPES in your Salesforce Account Manager > API Client > OpenID Connect > Allowed Scopes.

   When going live, you need to update some variables in the .env file with values from your live Customer Area. Check the Go-live checklist to learn about the variables you need to update when going live.

3. Run the following command to upload the .env file to MRT:

   npm run upload-env

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:

   npm run save-credentials -- --user YOUR_EMAIL --key YOUR_PERSONAL_MRT_API_KEY

3. Push your build to MRT:

   npm run push:env

4. Follow the steps to deploy the bundle in Salesforce Docs to the environment you have created.

Step 8 (Optional): Import the Adyen country list

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

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

   import {countryList} from '@adyen/adyen-salesforce-pwa'

   export const SHIPPING_COUNTRY_CODES = countryList

Step 9: 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.

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.