Start integrating with Salesforce Composable Storefront package
Choose your versionRequirements
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:
- You have installed the supported Node and npm versions.
- You have a Salesforce sandbox connected to your Salesforce Commerce Cloud (SFCC) instance.
- You have set up your environments, sites, locales and currencies, and product inventories.
- You have reached out to your Salesforce account team and enabled Managed Runtime (MRT) on your SFCC instance.
- Your have set your MRT permissions to Admin.
- 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.
-
Initiate the Salesforce PWA Kit starter project with the following command:
Expand viewCopy link to code blockCopy codenpx @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.
- Only if you link the retail app to your own sandbox, enter the following details at 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
- Launch your retail app with the following command:
Expand viewCopy link to code blockCopy code
npm run start
Step 2: Install the Adyen package in your local PWA app
-
In the root directory of your PWA app, install the Adyen Salesforce PWA npm package:
Expand viewCopy link to code blockCopy codenpm install @adyen/adyen-salesforce-pwa
-
In your PWA app, adjust the
overrides/app/ssr.js
file to import Adyen routes. You must import routes in the following order:-
Adyen routes. Add the following line:
Expand viewCopy link to code blockCopy codeimport {registerAdyenEndpoints} from '@adyen/adyen-salesforce-pwa/dist/ssr/index.js'
-
Default Salesforce routes.
-
Custom routes. We recommend you integrate and test the package without customizations first.
-
-
In the
overrides/app
folder of your Retail React app:-
In
routes.jsx
, import the Adyen CSS file:Expand viewCopy link to code blockCopy codeimport '@adyen/adyen-salesforce-pwa/dist/app/adyen.css'
-
Override the
checkout/index.jsx
file to wrap the Salesforce checkout provider with the Adyen checkout provider, passing the relevant hooks.Expand viewCopy link to code blockCopy codeimport 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' -
Override the
checkout/partials/payment.jsx
file to render theAdyenCheckout
component from theadyen-salesforce-pwa
package. See how you can render the component in our GitHub. -
Override the
checkout/confirmation.jsx
file to wrap the Salesforce checkout confirmation page with theAdyenCheckout
andAdyenCheckoutProvider
from theadyen-salesforce-pwa
package. See how you can render the components in our GitHub. -
Create an error page and register it in
routes.jsx
ascheckout/error
. See the example error page in our GitHub. -
Create a redirect page and register it in
routes.jsx
ascheckout/redirect
. See the example redirect page in our GitHub.
See the
routes.jsx
file on our GitHub to see how you can register pages. -
-
In your
package.json
file, add the following scripts:Expand viewCopy link to code blockCopy 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" -
Run the integration:
Expand viewCopy link to code blockCopy codenpm 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:
-
In the PWA Retail React app package, go to the
config/default.js
file. -
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 theid
.
See the PWA integration with the Adyen package on GitHub to see an example locale configuration.
-
In the
config/default.js
file, change the local attribute from none to query_param or path to display the locale in the URL. -
Only if you defined the
alias
field for locales, in theconfig/default.js
file, remove the comment markers forsiteAliases
, 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.
- Log in to your Customer Area.
- Go to Developers > API credentials, and select the API credential username for your integration, for example ws@Company.[YourCompanyAccount].
- Under Server settings > Authentication select the API key tab.
- Select Generate API key.
- Select the copy icon and store your API key securely in your system.
- 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:
-
In your Customer Area, go to Developers > Webhooks. If you want to configure webhooks for a merchant account, switch to that merchant account.
-
Select Webhook.
-
From the list of webhooks, next to Standard webhook, select Add.
-
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. -
Under Server configuration, configure the following:
Setting Description URL Your website URL followed by /api/adyen/webhook. Method JSON Encryption protocol TLSv1.3 -
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. -
Under Events settings, select the checkbox for the OFFER_CLOSED event code.
-
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.
-
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
- In your MRT environment, navigate to your project by selecting your Organization and Project.
- Select Environment Variables.
-
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 Your Adyen API key. YOUR_SITE_ID_ADYEN_MERCHANT_ACCOUNT Your Adyen merchant account name. YOUR_SITE_ID_ADYEN_CLIENT_KEY Your Adyen client key. YOUR_SITE_ID_ADYEN_ENVIRONMENT Use TEST. When you are ready to accept live payments, change the value to LIVE. YOUR_SITE_ID_ADYEN_WEBHOOK_USER The basic authentication username you entered when you set up webhooks. YOUR_SITE_ID_ADYEN_WEBHOOK_PASSWORD The basic authentication password you entered when you set up webhooks. YOUR_SITE_ID_ADYEN_HMAC_KEY The HMAC key you generated when you set up webhooks. YOUR_SITE_ID_ADYEN_LIVE_URL_PREFIX Only for Live
environmentYour 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 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 Your Salesforce site ID, for example, RefArch. COMMERCE_API_DEFAULT_SITE Your default Salesforce site, for example, RefArch. SCAPI_URL Your Salesforce Commerce API URL. Refer to Salesforce documentation for more information. OCAPI_URL Your Open Commerce API Url. Refer to Salesforce documentation for more information. ENVIRONMENT_ID Your MRT environment ID. PROJECT_ID Your project ID, for example, adyen-salesforce-pwa. COMMERCE_API_CLIENT_ID_PRIVATE Your Salesforce Commerce API client ID. To get your API credentials, create an API client in Salesforce. COMMERCE_API_CLIENT_SECRET Your Commerce API client secret for your Salesforce API client. SFCC_REALM_ID Your SFCC realm ID. SFCC_INSTANCE_ID Your SFCC instance ID. SFCC_OAUTH_SCOPES 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.
-
Follow the steps to generate a Personal MRT API key in Salesforce Docs.
-
In your Retail React App, save your credentials:
Expand viewCopy link to code blockCopy codenpm run save-credentials -- --user YOUR_EMAIL --key YOUR_PERSONAL_MRT_API_KEY
-
Push your build to MRT:
Expand viewCopy link to code blockCopy codenpm run push:env
-
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:
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.