Documentation

Apple Pay domain verification fails due to read-only root directory in Adobe Commerce

Last update: Tue Oct 07 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

In Adobe Commerce on Managed Services, Apple Pay domain verification fails because the root-level .well-known directory is restricted and not writable. To fix this, host the verification file in a writable directory and configure routing using either the .magento.app.yaml file or Fastly VCL snippets.

Description description

Environment

  • Product: Adobe Commerce on Managed Services
  • Version: 2.4.x
  • Affected Environment: Production, Staging

Issue/Symptoms

  • Unable to verify Apple Pay domain due to inability to write to the root directory.
  • The root directory is read-only.
  • 301 redirects are not allowed as per Apple’s requirements.

Resolution resolution

To successfully place the required file and configure it for Apple Pay domain verification, follow these steps:

  1. Create a .well-known directory under /pub/media/.
  2. Download the apple-developer-merchantid-domain-association.txt file from Apple Pay.
  3. Upload the file to /pub/media/.well-known/.

Then, configure routing using one of the following methods:

Method 1: Using .magento.app.yaml

  • Add the following configuration to your .magento.app.yaml file:

    code language-none 
    "/.well-known":
  root: "pub/media/.well-known"
  allow: true
  scripts: false
  expires: 1y

  • Push the changes to your environment.

Method 2: Using Fastly VCL Snippets

  • Log in to Magento Admin and go to: Stores > Configurations > ADVANCED > System

  • Expand Full Page Cache, then go to  Fastly Configuration  >   Custom VCL Snippets.

  • Click Create, and add the following rule:

    code language-none 
    if (req.url.path == "/.well-known/apple-app-site-association") {
  set req.url = "/media/.well-known/apple-app-site-association";
}

  • Use a friendly name like Apple_domain_association.

  • Set the type to recv and priority to 100.

  • Click Create, then click Upload Fastly VCL to apply the changes.

You should now be able to access the file at:
https://your_domain/.well-known/apple-developer-merchantid-domain-association.txt

recommendation-more-help
3d58f420-19b5-47a0-a122-5c9dab55ec7f