Guides

Digital Wallet Domain Verification

As part of your embedded checkout setup, you will need to complete a domain verification step during implementation. You’ll also need to perform this verification again any time you rename or change the domain where the checkout page is embedded.

Digital wallets, specifically Apple Pay, confirm that your organization controls the domain where the checkout page is embedded by checking for a small static text file at a specific location on that domain. This helps ensure Apple Pay is not used on domains outside of your control.

Because embedded checkout is served within your website or application, this verification file must be hosted on your domain rather than ours. That means some additional setup is required from your web, hosting, or IT team before we can complete Apple Pay domain validation for your embedded integration.

Please note that exact page architecture may vary by organization. The options below are intended as guidance to help your team get started.

Requirements

Please review the following requirements and share them with any additional teams that may assist with this setup:

  • Do not rename the file.
  • Do not change the file contents.
  • Do not wrap the file in HTML or route it through an application page.
  • The file must be reachable directly at the exact location we provide.
  • The file must be served with a plain-text content type.

Example target location:

https://your-checkout-domain.example/.well-known/apple-developer-merchantid-domain-association.txt

Option 1: Traditional web server or reverse proxy

Use this path if your site is served through IIS, Nginx, Apache, or a similar web server or reverse proxy.

How to serve the file:

  1. Locate the web root or static-files directory for the site that serves the checkout page.
  2. Create a folder named .well-known at that site root if it does not already exist.
  3. Place the file we provide into that folder.
  4. Make sure the final deployed path is: /.well-known/apple-developer-merchantid-domain-association.txt
  5. Reload or deploy the web server configuration if needed.
  6. Open the full HTTPS URL in a browser and confirm the file is publicly reachable.

Common pitfalls

  • Some server configurations block dot-prefixed directories like .well-known by default.
  • Some reverse proxies rewrite unknown paths to the application instead of serving a file.
  • Some sites redirect all unmatched URLs to index.html; that must not happen for this file.
  • If your site uses caching, purge or invalidate the cache after deploying the file.

Option 2: Frontend app with public/static assets

Use this path if the checkout page is part of a frontend app built with a framework such as React, Vue, or Angular and the deployed site includes a public or static assets folder.

How to serve the file:

  1. Locate the folder in the app that is copied to the site root during build or deployment. This is often named something like public, or static.
  2. Inside that folder, create a .well-known directory if it does not already exist.
  3. Add the file we provide at this path inside the source tree: public/.well-known/apple-developer-merchantid-domain-association.txt or the equivalent for your framework/build system.
  4. Run the normal build and deployment process for the site.
  5. After deployment, open the final HTTPS URL and confirm that the file is being served directly.

Common pitfalls

  • Make sure the build process preserves dot-prefixed directories and files.
  • Make sure the hosting layer serves that file as a static asset instead of routing it through the SPA.
  • If the site is deployed behind a CDN, purge the CDN cache after release.
  • If there are separate prod and non-prod builds, make sure the correct file is added to its corresponding environment.

Option 3: CDN or static hosting platform

Use this path if the site is served from a CDN, object storage bucket, static hosting platform, or managed edge platform.

Examples include S3 + CloudFront, Azure Blob Storage + CDN, Akamai-backed static content, Netlify, Vercel, Cloudflare Pages, or another managed static hosting setup.

How to serve the file:

  1. Identify the origin or content source that backs the public site.
  2. Upload the file we provide into the origin at this exact key/path: .well-known/apple-developer-merchantid-domain-association.txt
  3. If your CDN has routing or edge rules, confirm that requests to that path are served as a static file and are not redirected or rewritten.
  4. Purge or invalidate the CDN cache for that path after upload.
  5. Open the public HTTPS URL and confirm that the file is reachable from the public internet.

Common pitfalls

  • Some CDNs require an explicit content-type override or a rule to allow plain-text delivery.
  • Some platforms rewrite all unmatched routes to the app entry point; exclude this file path from those rules.
  • Some WAF or bot-protection layers may block Apple’s fetch even if the file seems reachable to you.
  • Some environments separate origin content by environment; make sure the file is uploaded to the environment tied to the checkout domain we specify.

If none of the above examples match

If your site is hosted by another vendor or managed through a platform not listed above, send that team these exact requirements:

Host this exact file, on this exact domain, at this exact path, over HTTPS, with no content changes, with no HTML wrapper, and no redirect to another page.

In most cases, that is enough for a web platform team to implement the change even if they use a different stack.