# How to Configure the Apple Pay Merchant Certificate in Adyen Salesforce Commerce Cloud

> Configure your Apple Pay merchant certificate in Adyen Salesforce Commerce Cloud. Learn to set domain association string and upload PKCS #12 files for seamless integration.

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

---

**The Apple Pay merchant certificate configuration requires setting the domain association string in Business Manager custom preferences while either using an Adyen-managed certificate or uploading your own PKCS #12 file through the Salesforce Apple Pay cartridge.**

The Adyen Salesforce Commerce Cloud integration supports Apple Pay through a combination of domain verification and merchant certificate management. Configuring the Apple Pay merchant certificate involves two distinct technical components: the domain association file served from a well-known URL and the actual cryptographic certificate used to authenticate payment sessions. This guide walks through the exact steps and source code locations needed to enable Apple Pay in your SFCC storefront.

## Understanding the Two Configuration Components

The integration relies on separate mechanisms for domain ownership verification and payment processing authentication.

### Apple Pay Domain Association

The **domain association** is a verification string that Apple requires to validate merchant domain ownership. This text must be served from `/.well-known/apple-developer-merchantid-domain-association`. According to the source code 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 `getApplePayDomainAssociation()` function reads this value from the Business Manager custom preference `Adyen_ApplePay_DomainAssociation` at line 86.

### Merchant Certificate (PKCS #12)

The **merchant certificate** is the `.p12` file containing your Apple Pay merchant identifier and private key. The repository does not store this certificate directly. Instead, you have two options: use an **Adyen-provided certificate** managed entirely by Adyen, or manage your own certificate through the **Salesforce Apple Pay cartridge** (a separate repository). The certificate is used by the web component when creating an `ApplePaySession` on the checkout page.

## Step-by-Step Configuration Process

### Choose Your Certificate Source

You must first decide between the two certificate management approaches:

- **Adyen-managed certificate**: Adyen generates and hosts the certificate for you. No additional upload steps are required; the integration automatically uses Adyen's hosted certificate.
- **Self-managed certificate**: Install the Salesforce Apple Pay cartridge separately and upload your `.p12` file through its Business Manager interface. This gives you direct control over the certificate lifecycle.

### Configure the Domain Association

1. Obtain the domain association string from your Apple Developer account or the Salesforce Apple Pay cartridge interface.
2. Navigate to **Merchant Tools → Custom Preferences → Adyen → Apple Pay Domain Association** in Business Manager.
3. Paste the string into the textarea field rendered by the `lpmSettings.isml` template at `src/cartridges/bm_adyen/cartridge/templates/default/adyenSettings/settingCards/lpmSettings.isml` (line 37).

The system stores this value in the custom 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).

### Enable Apple Pay Express (Optional)

To enable Apple Pay Express checkout functionality, toggle three Boolean preferences in Business Manager:

- `ApplePayExpress_Enabled`
- `ApplePayExpress_Pdp_Enabled` 
- `ApplePayExpress_ShippingPage_Enabled`

These custom attributes are declared in [`system-objecttype-extensions.xml`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/system-objecttype-extensions.xml) around line 528, allowing express checkout buttons to appear on product detail pages and the shipping stage.

### Deploy the Verification Endpoint

The **RedirectURL** controller automatically handles domain verification requests. When Apple Pay requests `/.well-known/apple-developer-merchantid-domain-association`, the controller retrieves the stored domain association string via `AdyenConfigs.getApplePayDomainAssociation()` and returns it to Apple's servers. This endpoint is wired through the platform constants defined in [`src/cartridges/int_adyen_SFRA/cartridge/adyen/config/constants.js`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/src/cartridges/int_adyen_SFRA/cartridge/adyen/config/constants.js) at line 163.

No code changes are required to deploy this endpoint; it activates once the custom preference contains the domain association value.

### Test the Integration

Use Apple's Sandbox environment to initiate test transactions. The frontend JavaScript in [`applepay.js`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/applepay.js) at `src/cartridges/app_adyen_SFRA/cartridge/client/default/js/adyen/express/paymentMethods/applepay/` calls `ApplePaySession.canMakePayments()` to verify compatibility, then creates a session using the merchant identifier matching your configured certificate.

## Implementation Details

### Reading the Configuration

The server-side code retrieves the domain association through the AdyenConfigs utility:

```javascript
// src/cartridges/int_adyen_SFRA/cartridge/adyen/utils/adyenConfigs.js
var AdyenConfigs = require('*/cartridge/adyen/utils/adyenConfigs');
var domainAssociation = AdyenConfigs.getApplePayDomainAssociation(); 
response.getWriter().print(domainAssociation);

```

### Business Manager Interface Template

The textarea for entering the domain association appears in the Adyen Settings card:

```html
<!-- src/cartridges/bm_adyen/cartridge/templates/default/adyenSettings/settingCards/lpmSettings.isml -->
<label for="applePayDomain">Apple Pay Domain Association</label>
<textarea
    name="Adyen_ApplePay_DomainAssociation"
    id="applePayDomain"
    aria-describedby="applePayDomainHelp">${AdyenConfigs.getApplePayDomainAssociation() || ''}</textarea>

```

### Frontend Session Creation

The client-side JavaScript initiates the payment session using the configured merchant identifier:

```javascript
// src/cartridges/app_adyen_SFRA/cartridge/client/default/js/adyen/express/paymentMethods/applepay/applepay.js
class ApplePay {
    async createSession() {
        const response = await fetch('/path/to/your/applePaySession', {
            method: 'POST',
            body: JSON.stringify({ /* order data */ })
        });
        const sessionData = await response.json();
        const session = new ApplePaySession(6, sessionData);
        // Session initialization continues...
    }
}

```

## Summary

- Store the domain association string in the `Adyen_ApplePay_DomainAssociation` custom preference, read by `AdyenConfigs.getApplePayDomainAssociation()` 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).
- Choose between an **Adyen-managed certificate** (no upload required) or a **self-managed certificate** (requires the Salesforce Apple Pay cartridge).
- The **RedirectURL** controller automatically serves verification files from `/.well-known/apple-developer-merchantid-domain-association` using the stored domain association value.
- Enable Apple Pay Express checkout by toggling Boolean preferences 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).
- The frontend implementation in [`applepay.js`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/applepay.js) handles session creation using the configured merchant identifier.

## Frequently Asked Questions

### Where do I store the Apple Pay domain association string?

Store the domain association string in the **Adyen_ApplePay_DomainAssociation** custom preference within Business Manager. The `lpmSettings.isml` template renders the textarea interface at `src/cartridges/bm_adyen/cartridge/templates/default/adyenSettings/settingCards/lpmSettings.isml`, and the value is persisted in the custom attributes 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).

### Do I need to upload the merchant certificate to Business Manager?

No, the merchant certificate is not uploaded through the standard Adyen cartridge interface. If using an **Adyen-managed certificate**, Adyen hosts the certificate automatically. If using your own certificate, you must install the separate **Salesforce Apple Pay cartridge** and upload the `.p12` file through that cartridge's Business Manager settings.

### How does the domain verification endpoint work?

The **RedirectURL** controller reads the domain association string via `AdyenConfigs.getApplePayDomainAssociation()` and returns it when Apple Pay requests the path `/.well-known/apple-developer-merchantid-domain-association`. This path is defined as a constant in [`src/cartridges/int_adyen_SFRA/cartridge/adyen/config/constants.js`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/src/cartridges/int_adyen_SFRA/cartridge/adyen/config/constants.js) at line 163. No manual endpoint configuration is required.

### What controls the Apple Pay Express checkout settings?

Apple Pay Express checkout is controlled by three Boolean custom preferences: `ApplePayExpress_Enabled`, `ApplePayExpress_Pdp_Enabled`, and `ApplePayExpress_ShippingPage_Enabled`. These are declared 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) around line 528 and enable express payment buttons on product detail pages and the shipping stage of checkout.