# How to Configure Apple Pay Express Checkout in Salesforce Commerce Cloud

> Configure Apple Pay Express checkout in Salesforce Commerce Cloud easily. Follow our guide to enable seamless payments on PDP and shipping pages for a better customer experience.

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

---

**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`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/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`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/adyenConfigs.js) to read Business Manager preferences and expose them to the frontend.

In [`src/cartridges/int_adyen_SFRA/cartridge/adyen/utils/adyenConfigs.js`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/src/cartridges/int_adyen_SFRA/cartridge/adyen/utils/adyenConfigs.js), the following methods retrieve the Apple Pay Express states:

```javascript
// 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`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/getCheckoutExpressPaymentMethods.js). This script constructs three distinct objects—`expressPaymentMethodsCart`, `expressPaymentMethodsPdp`, and `expressPaymentMethodsShipping`—that map the backend preferences to frontend flags:

```javascript
// 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`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/src/cartridges/int_adyen_SFRA/cartridge/controllers/RedirectURL.js):

```javascript
// 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`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/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`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/adyenSettings.js). This file renders three switches corresponding to the backend preferences:

```javascript
// 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`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/expressPayments.js):

```javascript
// 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`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/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`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/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`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/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`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/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`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/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.