# How to Set Up Amazon Pay Express Checkout Flow in Salesforce Commerce Cloud

> Learn to set up Amazon Pay Express checkout flow in Salesforce Commerce Cloud. Integrate Adyen's cartridge, enable payments, and wire frontend JavaScript for a seamless checkout experience. Maximize conversions today.

- Repository: [Adyen/adyen-salesforce-commerce-cloud](https://github.com/adyen/adyen-salesforce-commerce-cloud)
- Tags: how-to-guide
- Published: 2026-02-23

---

**To set up Amazon Pay Express checkout in the Adyen Salesforce Commerce Cloud cartridge, enable the payment method in Business Manager, detect the `amazonCheckoutSessionId` query parameter in `checkoutButtons.isml`, and wire the frontend JavaScript to call the `GetExpressPaymentMethods` and `SaveExpressShopperDetails` endpoints while persisting shopper details in the `amazonExpressShopperDetails` basket attribute.**

Amazon Pay Express checkout enables one-step purchases directly from the cart page in Salesforce Commerce Cloud (SFRA) storefronts. This implementation leverages the Adyen Web SDK to render the payment button, collect shopper details, and complete the transaction without redirecting to a separate checkout page. Below is the complete technical guide based on the `adyen/adyen-salesforce-commerce-cloud` repository source code.

## Enable Amazon Pay in Business Manager

Before implementing the frontend or backend logic, activate Amazon Pay in your Adyen configuration. Navigate to **Administration → Sites → Merchant Tools → Payments → Adyen → Payment Methods** in Business Manager and ensure the Amazon Pay payment method is enabled for your site.

## Configure SFRA Template Detection

The flow begins when Amazon redirects the shopper back to your storefront with a session identifier. In `src/cartridges/app_adyen_SFRA/cartridge/templates/default/cart/checkoutButtons.isml`, detect the `amazonCheckoutSessionId` query parameter and inject the required JavaScript globals:

```html
<isif condition="${request.getHttpQueryString() && request.getHttpQueryString().indexOf('amazonCheckoutSessionId') > -1}">
  <script type="text/javascript">
    window.clientKey = "...";
    window.saveShopperDetailsURL = "${URLUtils.https('Adyen-SaveExpressShopperDetails')}";
    window.returnUrl = "${URLUtils.https('Checkout-Begin', 'stage', 'payment')}";
    window.getExpressPaymentMethodsURL = "${URLUtils.https('Adyen-GetExpressPaymentMethods')}";
    var amazonCheckoutSessionId = "${AdyenHelper.encodeHtml(request.getHttpQueryString().split('=')[1])}";
    window.amazonCheckoutSessionId = amazonCheckoutSessionId;
  </script>
  <isscript>
    assets.addJs('/js/adyen/express/paymentMethods/amazonpay/amazonPayExpressPart2.js');
  </isscript>
</isif>

```

This conditional block ensures that [`amazonPayExpressPart2.js`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/amazonPayExpressPart2.js) only loads when an Amazon Pay session is present, preventing unnecessary script execution on standard cart pages.

## Implement Frontend JavaScript Components

The frontend implementation splits responsibilities between two files: one for component configuration and one for flow orchestration.

### Configure the Express Component in amazonPayExpressPart1.js

The [`src/cartridges/app_adyen_SFRA/cartridge/client/default/js/adyen/express/paymentMethods/amazonpay/amazonPayExpressPart1.js`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/src/cartridges/app_adyen_SFRA/cartridge/client/default/js/adyen/express/paymentMethods/amazonpay/amazonPayExpressPart1.js) file defines the `AmazonPay` class that configures the Adyen Web SDK with Express-specific settings:

```javascript
class AmazonPay {
  constructor(config, applicationInfo, adyenTranslations) {
    this.returnUrl = window.returnUrl;
    this.showPayButton = true;
    this.isExpress = true;
    // ...
  }
  
  getConfig() {
    return {
      configuration: this.config,
      showPayButton: this.showPayButton,
      isExpress: this.isExpress,
      returnUrl: this.returnUrl,
      productType: 'PayAndShip',
    };
  }
  
  async getComponent() {
    const checkout = await initializeCheckout(this.applicationInfo, this.translations);
    const amazonPayConfig = this.getConfig();
    return window.AdyenWeb.createComponent('amazonpay', checkout, amazonPayConfig);
  }
}

```

Setting `isExpress: true` signals to the Adyen Web SDK that this component should collect shipping and billing details directly from the Amazon Pay wallet, bypassing the standard SFRA checkout forms.

### Orchestrate the Flow in amazonPayExpressPart2.js

The [`src/cartridges/app_adyen_SFRA/cartridge/client/default/js/adyen/express/paymentMethods/amazonpay/amazonPayExpressPart2.js`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/src/cartridges/app_adyen_SFRA/cartridge/client/default/js/adyen/express/paymentMethods/amazonpay/amazonPayExpressPart2.js) file handles the complete user journey:

1.  Fetches payment configuration from the backend
2.  Mounts the Amazon Pay button
3.  Retrieves shopper details from Amazon
4.  Saves details to the SFCC basket
5.  Displays the shipping address and available methods

```javascript
async function mountAmazonPayComponent() {
  const amazonPayNode = document.getElementById('amazon-container');
  
  // Step 1: Fetch configuration from SFCC
  const paymentMethodsData = await getExpressPaymentMethods();
  
  // Step 2: Initialize Adyen Checkout
  const checkout = await window.AdyenWeb.AdyenCheckout({ /* config */ });
  const amazonConfig = { 
    /* ... */ 
    amazonCheckoutSessionId: window.amazonCheckoutSessionId 
  };
  
  // Step 3: Create and mount component
  const amazonPayComponent = window.AdyenWeb.createComponent('amazonpay', checkout, amazonConfig);
  amazonPayComponent.mount(amazonPayNode);
  
  // Step 4: Get shopper details from Amazon
  const shopperDetails = await amazonPayComponent.getShopperDetails();
  
  // Step 5: Persist to SFCC basket
  await saveShopperDetails(shopperDetails);
  
  // Step 6: Display address and shipping options
  showAddressDetails(shopperDetails);
}

// Auto-execute when script loads
(async () => {
  await mountAmazonPayComponent();
})();

```

The `saveShopperDetails` function posts the data to the `Adyen-SaveExpressShopperDetails` endpoint, while `showAddressDetails` renders the address review UI with an optional *Change* button for shoppers who need to modify their information.

## Expose Backend Controller Endpoints

The [`src/cartridges/int_adyen_SFRA/cartridge/controllers/Adyen.js`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/src/cartridges/int_adyen_SFRA/cartridge/controllers/Adyen.js) file must register two HTTPS POST routes to support the frontend:

```javascript
server.post('GetExpressPaymentMethods', 
  server.middleware.https, 
  csrf.generateToken, 
  adyen.getCheckoutExpressPaymentMethods);

server.post('SaveExpressShopperDetails', 
  server.middleware.https, 
  csrf.validateRequest, 
  adyen.saveExpressShopperDetails);

```

**`GetExpressPaymentMethods`** returns a JSON payload containing the Amazon Pay configuration object with `merchantId`, `storeId`, `region`, and `publicKeyId`. The frontend uses this to initialize the Adyen Web SDK.

**`SaveExpressShopperDetails`** accepts the shopper details JSON and the payment method type. The underlying `adyen.saveExpressShopperDetails` middleware extracts the data and persists it to the current basket before returning available shipping methods.

## Persist Data with Custom Basket Attributes

To maintain shopper details across the session, the implementation uses a custom attribute on the Basket object. In [`metadata/site_import/meta/system-objecttype-extensions.xml`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/metadata/site_import/meta/system-objecttype-extensions.xml), define the `amazonExpressShopperDetails` attribute:

```xml
<attribute-definition attribute-id="amazonExpressShopperDetails">
  <display-name xml:lang="x-default">amazonExpressShopperDetails</display-name>
  <type>string</type>
  <size>4000</size>
</attribute-definition>

```

The backend controller serializes the shopper details as a JSON string and stores it in `basket.custom.amazonExpressShopperDetails`. This persistence allows the final payment request to access the address and payment descriptor without requiring the shopper to re-enter information.

## Complete Integration Flow

The Amazon Pay Express checkout follows this sequence:

1.  **Redirection**: Amazon redirects the shopper to your cart URL with `?amazonCheckoutSessionId=XYZ`.
2.  **Detection**: `checkoutButtons.isml` detects the parameter, injects global variables, and loads [`amazonPayExpressPart2.js`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/amazonPayExpressPart2.js).
3.  **Configuration**: The frontend calls `Adyen-GetExpressPaymentMethods` to retrieve merchant credentials.
4.  **Rendering**: The Adyen Web SDK renders the Amazon Pay button inside the `#amazon-container` div.
5.  **Authorization**: The shopper authenticates with Amazon and approves the payment.
6.  **Data Collection**: `amazonPayComponent.getShopperDetails()` returns the name, address, and payment descriptor.
7.  **Persistence**: The frontend POSTs to `Adyen-SaveExpressShopperDetails`, storing the JSON in `basket.custom.amazonExpressShopperDetails`.
8.  **Shipping Selection**: The backend returns available shipping methods, which the frontend displays alongside the confirmed address.
9.  **Completion**: The shopper clicks **Pay**, triggering the final Adyen `/payments` request that includes the stored details.

## Summary

-   **Enable Amazon Pay** in Adyen Business Manager before modifying code.
-   **Detect session IDs** in `checkoutButtons.isml` to conditionally load Express checkout scripts.
-   **Use [`amazonPayExpressPart1.js`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/amazonPayExpressPart1.js)** to configure the Express component with `isExpress: true` and `productType: 'PayAndShip'`.
-   **Orchestrate the flow** in [`amazonPayExpressPart2.js`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/amazonPayExpressPart2.js) by mounting the component, calling `getShopperDetails()`, and posting to `SaveExpressShopperDetails`.
-   **Register endpoints** in [`controllers/Adyen.js`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/controllers/Adyen.js) for `GetExpressPaymentMethods` and `SaveExpressShopperDetails`.
-   **Persist data** using the `amazonExpressShopperDetails` custom attribute defined in [`system-objecttype-extensions.xml`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/system-objecttype-extensions.xml).

## Frequently Asked Questions

### What triggers the Amazon Pay Express checkout flow?

The flow initiates when Amazon redirects the shopper back to your storefront with an `amazonCheckoutSessionId` query parameter in the URL. The `checkoutButtons.isml` template detects this parameter and loads the [`amazonPayExpressPart2.js`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/amazonPayExpressPart2.js) orchestration script, which bootstraps the Adyen Web SDK and renders the payment interface.

### How does the frontend communicate shopper details to the backend?

After the shopper authorizes the payment, the frontend calls `amazonPayComponent.getShopperDetails()` to retrieve the address and payment descriptor. The `saveShopperDetails` function then POSTs this data as JSON to the `Adyen-SaveExpressShopperDetails` endpoint. The backend controller stores this information in the `amazonExpressShopperDetails` custom attribute on the basket.

### Where are the shopper details stored during the checkout process?

Shopper details are serialized as a JSON string and stored in the `basket.custom.amazonExpressShopperDetails` attribute, defined in [`metadata/site_import/meta/system-objecttype-extensions.xml`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/metadata/site_import/meta/system-objecttype-extensions.xml). This custom attribute has a maximum length of 4000 characters and persists the data through the session, making it available for the final payment authorization request.

### What is the purpose of the `GetExpressPaymentMethods` endpoint?

The `Adyen-GetExpressPaymentMethods` endpoint returns the Amazon Pay configuration object required to initialize the Adyen Web SDK on the frontend. This includes sensitive merchant credentials like `merchantId`, `storeId`, and `publicKeyId` that the SDK needs to render the Amazon Pay button and handle the Express checkout protocol securely.