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

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:

<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 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 file defines the AmazonPay class that configures the Adyen Web SDK with Express-specific settings:

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

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 file must register two HTTPS POST routes to support the frontend:

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, define the amazonExpressShopperDetails attribute:

<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.
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 to configure the Express component with isExpress: true and productType: 'PayAndShip'.
• Orchestrate the flow in amazonPayExpressPart2.js by mounting the component, calling getShopperDetails(), and posting to SaveExpressShopperDetails.
• Register endpoints in controllers/Adyen.js for GetExpressPaymentMethods and SaveExpressShopperDetails.
• Persist data using the amazonExpressShopperDetails custom attribute defined in 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 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}