How to Configure Apple Pay Express Checkout in Salesforce Commerce Cloud

Enable Apple Pay Express checkout in Salesforce Commerce Cloud by configuring three custom preferences in Business Manager—ApplePayExpress_Enabled, ApplePayExpress_Pdp_Enabled, and ApplePayExpress_ShippingPage_Enabled—and serving the domain association file through the RedirectURL controller.

The adyen-salesforce-commerce-cloud integration streamlines one-tap payments by allowing shoppers to complete purchases directly from the cart, product detail page (PDP), or shipping methods page using Apple Pay Express. Configuring this feature requires setting custom preferences in Business Manager, exposing those settings through backend utilities, and implementing the client-side Apple Pay component. This guide details the exact file paths and method implementations needed to activate Apple Pay Express checkout in your Salesforce Commerce Cloud environment.

Enabling Apple Pay Express in Business Manager

Apple Pay Express functionality is controlled through four Custom Preferences managed in Business Manager under Administration → Site Preferences → Custom Preferences. The UI for these toggles is generated by adyenSettings.js in the Business Manager cartridge.

Configure the following preferences:

• ApplePayExpress_Enabled – Activates Apple Pay Express on the cart and mini-cart pages.
• ApplePayExpress_Pdp_Enabled – Activates Apple Pay Express on the product detail page.
• ApplePayExpress_ShippingPage_Enabled – Activates Apple Pay Express on the shipping methods page.
• Adyen_ApplePay_DomainAssociation – Stores the raw content of your Apple Pay Domain Association file, which must be served at /.well-known/apple-pay-merchant-id for domain verification.

Set these values to true (or paste the certificate content for the domain association) and save the site preferences to enable the backend flags.

Exposing Preferences Through Backend Helpers

The integration uses centralized getter methods in adyenConfigs.js to read Business Manager preferences and expose them to the frontend.

In src/cartridges/int_adyen_SFRA/cartridge/adyen/utils/adyenConfigs.js, the following methods retrieve the Apple Pay Express states:

// src/cartridges/int_adyen_SFRA/cartridge/adyen/utils/adyenConfigs.js
isApplePayExpressEnabled() {
  return getCustomPreference('ApplePayExpress_Enabled');
}

isApplePayExpressOnPdpEnabled() {
  return getCustomPreference('ApplePayExpress_Pdp_Enabled');
}

isApplePayExpressOnShippingPageEnabled() {
  return getCustomPreference('ApplePayExpress_ShippingPage_Enabled');
}

These getters are consumed by the express payment methods endpoint in getCheckoutExpressPaymentMethods.js. This script constructs three distinct objects—expressPaymentMethodsCart, expressPaymentMethodsPdp, and expressPaymentMethodsShipping—that map the backend preferences to frontend flags:

// src/cartridges/int_adyen_SFRA/cartridge/scripts/expressPayments/getCheckoutExpressPaymentMethods.js
const expressPaymentMethodsCart = {
  [constants.PAYMENTMETHODS.APPLEPAY]: !!AdyenConfigs.isApplePayExpressEnabled(),
  // ...
};

const expressPaymentMethodsPdp = {
  [constants.PAYMENTMETHODS.APPLEPAY]: !!AdyenConfigs.isApplePayExpressOnPdpEnabled(),
  // ...
};

const expressPaymentMethodsShipping = {
  [constants.PAYMENTMETHODS.APPLEPAY]: !!AdyenConfigs.isApplePayExpressOnShippingPageEnabled(),
  // ...
};

The endpoint returns these objects as cartExpressMethods, pdpExpressMethods, and shippingExpressMethods in the JSON response, which the frontend uses to conditionally render Apple Pay buttons.

Serving the Domain Association File

Apple requires merchants to host a domain verification file at /.well-known/apple-pay-merchant-id. The RedirectURL controller handles these requests by reading the Adyen_ApplePay_DomainAssociation preference and returning its raw content.

In src/cartridges/int_adyen_SFRA/cartridge/controllers/RedirectURL.js:

// src/cartridges/int_adyen_SFRA/cartridge/controllers/RedirectURL.js
if (origin.match(constants.APPLE_DOMAIN_URL)) {
  const applePayDomainAssociation = AdyenConfigs.getApplePayDomainAssociation();
  res.setHttpHeader(dw.system.Response.CONTENT_TYPE, 'text/plain');
  response.getWriter().print(applePayDomainAssociation);
  return null;
}

Ensure the APPLE_DOMAIN_URL constant defined in constants.js correctly matches the .well-known/apple-pay-merchant-id path. Once published, this endpoint validates your domain with Apple Pay.

Frontend Configuration and Button Rendering

The Business Manager UI for toggling Apple Pay Express is defined in adyenSettings.js. This file renders three switches corresponding to the backend preferences:

// src/cartridges/bm_adyen/cartridge/static/default/js/adyenSettings.js
{
  id: 'applepay',
  text: 'Apple Pay Express',
  toggles: [
    { name: 'ApplePayExpress_Enabled', text: 'Cart / mini cart', checked: window.isApplePayEnabled },
    { name: 'ApplePayExpress_Pdp_Enabled', text: 'Product details page', checked: window.isApplePayExpressOnPdpEnabled },
    { name: 'ApplePayExpress_ShippingPage_Enabled', text: 'Shipping methods page', checked: window.isApplePayExpressOnShippingPageEnabled },
  ],
}

On the storefront, the client-side code checks the flags returned by the express payment endpoint before initializing the Apple Pay button. In expressPayments.js:

// src/cartridges/app_adyen_SFRA/cartridge/client/default/js/adyen/express/product/expressPayments.js
if (expressMethods.includes('applepay')) {
  const applePay = new ApplePay(config, appInfo, translations, isExpressPdp, amount);
  renderApplePayButton(applePay);
}

The ApplePay class is imported from paymentMethods/applepay/applepay.js and instantiated with configuration objects, application info, translations, a boolean flag indicating if the context is PDP (isExpressPdp), and the order amount.

Implementing the Apple Pay Checkout Flow

The Apple Pay class located at src/cartridges/app_adyen_SFRA/cartridge/client/default/js/adyen/express/paymentMethods/applepay/applepay.js manages the complete Express checkout flow.

Key methods include:

• onAuthorized – Extracts shipping and contact information from the Apple Pay session and constructs a customer object for the Adyen payment request.
• onSubmit – Sends payment data to the payment-from-component endpoint (paymentFromComponentURL), creates a hidden confirmation form, and triggers an Express redirect if on the PDP.
• selectShippingMethod / getShippingMethod – Communicates with server-side endpoints to fetch or update shipping methods during the Apple Pay sheet interaction.
• handleAuthorised – Resolves the payment promise with the resultCode and submits the hidden form to complete the order.
• handleError – Resolves with an error flag if the payment fails.

The class operates identically across cart, PDP, and shipping pages, using the isExpressPdp flag only to determine whether to redirect the user after successful authorization.

Complete Configuration Checklist

Follow these steps to fully activate Apple Pay Express:

1. Upload the domain association certificate into the Adyen_ApplePay_DomainAssociation custom preference in Business Manager.
2. Enable the required toggles (ApplePayExpress_Enabled, ApplePayExpress_Pdp_Enabled, ApplePayExpress_ShippingPage_Enabled) based on which pages should display the button.
3. Publish the site to make the RedirectURL controller accessible at /.well-known/apple-pay-merchant-id.
4. Verify the backend flags by calling /Adyen-Express-GetCheckoutExpressPaymentMethods and confirming that cartExpressMethods, pdpExpressMethods, or shippingExpressMethods contains applepay.
5. Test in Safari on a compatible device to ensure the Apple Pay button renders and completes the checkout flow successfully.

Summary

• Configure four custom preferences in Business Manager to control Apple Pay Express visibility on cart, PDP, and shipping pages, plus domain verification.
• Use adyenConfigs.js getter methods to expose preference values to the frontend through the express payment methods endpoint.
• Serve the domain association file via the RedirectURL controller at the /.well-known/apple-pay-merchant-id path.
• Render the Apple Pay button conditionally based on flags returned by getCheckoutExpressPaymentMethods.js.
• Process payments using the ApplePay client-side class, which handles authorization, shipping selection, and order submission.

Frequently Asked Questions

What custom preferences are required to enable Apple Pay Express in Salesforce Commerce Cloud?

You must configure ApplePayExpress_Enabled for the cart, ApplePayExpress_Pdp_Enabled for the product detail page, and ApplePayExpress_ShippingPage_Enabled for the shipping page. Additionally, populate Adyen_ApplePay_DomainAssociation with your Apple Pay domain verification certificate. These are set in Business Manager under Site Preferences.

How does the domain association file get served for Apple Pay verification?

The RedirectURL controller intercepts requests to /.well-known/apple-pay-merchant-id and returns the raw content stored in the Adyen_ApplePay_DomainAssociation preference with a text/plain content type. This satisfies Apple's domain verification requirement.

Which controller handles the Apple Pay domain association request?

The RedirectURL controller in src/cartridges/int_adyen_SFRA/cartridge/controllers/RedirectURL.js handles the domain association request. It checks the request origin against constants.APPLE_DOMAIN_URL and prints the certificate content using AdyenConfigs.getApplePayDomainAssociation().

Can Apple Pay Express be enabled only for specific pages?

Yes. The three separate preferences (ApplePayExpress_Enabled, ApplePayExpress_Pdp_Enabled, ApplePayExpress_ShippingPage_Enabled) allow you to enable Apple Pay Express independently for the cart, product detail page, and shipping methods page. Only enable the toggles for the specific pages where you want the button to appear.

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