Safari Merchant Domain Verification via Association Files

This article explains the technical process of how the Safari web browser and Apple's ecosystem verify merchant domain ownership using the apple-developer-merchantid-domain-association file. It covers the initial server configuration, the cryptographic relationship between the Merchant ID and the domain, and how Safari relies on this verification at runtime to securely render the Apple Pay payment sheet.

The Role of the Domain Association File

To accept Apple Pay on the web, a merchant must prove they control the domain where the transaction occurs. The apple-developer-merchantid-domain-association file is a unique, cryptographically signed file generated by Apple for a specific Merchant ID and domain name. It contains a verification token and signature that binds the merchant’s identity to their web server.

Step 1: Hosting the Verification File

Before Safari can process any payments, the merchant must host the association file on their web server. The server must meet strict criteria for verification to succeed:

  • Exact Path: The file must be placed at https://[DOMAIN_NAME]/.well-known/apple-developer-merchantid-domain-association.
  • HTTPS Protocol: The file must be served over HTTPS using TLS 1.2 or higher with a valid, publicly trusted SSL/TLS certificate.
  • Direct Access: The file must be externally accessible to Apple's web crawlers without requiring authentication, and it cannot be behind a proxy or redirect (HTTP 3xx responses will cause verification to fail).
  • Content-Type: The server must serve the file as plain text or binary data without altering its contents or appending file extensions like .txt or .json.

Step 2: Apple Server Pre-Verification

Technically, the Safari browser does not download the apple-developer-merchantid-domain-association file directly when a user visits a website. Instead, verification is a two-part process involving Apple’s backend servers and Safari's runtime checks.

When the merchant clicks "Verify" in the Apple Developer Portal (or registers the domain via the Apple Pay Web Merchant Registration API), Apple’s servers make an HTTPS GET request to the .well-known URL on the merchant's server. Apple's servers read the file, validate the cryptographic signature inside it, and confirm that it matches the registered Merchant ID and the domain from which it was fetched. Once confirmed, Apple marks the domain as verified in its central database.

Step 3: How Safari Verifies the Domain at Checkout

Safari leverages the pre-verified status of the domain every time a customer initiates an Apple Pay transaction. This happens through a process called Merchant Validation.

When a user clicks the Apple Pay button in Safari, the following sequence occurs:

  1. Payment Request Initialization: Safari triggers the onvalidatemerchant event in the browser via the Apple Pay JS API. At this stage, Safari displays the payment sheet in a loading state and waits for proof that the current domain is authorized.
  2. Session Request: The merchant's frontend JavaScript requests a secure payment session from the merchant's backend server.
  3. Apple Server Handshake: The merchant's backend server makes a server-to-server POST request to Apple’s validation URL (provided by Safari in the event). This request includes the Merchant ID, the Merchant Identity Certificate, and the exact domain name where the user is currently shopping (window.location.hostname).
  4. Verification Check: Apple's servers check their database to ensure the domain passed in the request has already been verified via the apple-developer-merchantid-domain-association file and is linked to the provided Merchant ID.
  5. Session Return: If the domain is verified, Apple generates a cryptographically signed Merchant Session object and sends it back to the merchant's server, which then passes it to the Safari browser.
  6. Safari Validation: The merchant's frontend passes this session object into Safari’s completeMerchantValidation method. Safari decrypts and validates Apple's signature on the session object, confirming that the domain in the browser's address bar matches the verified domain inside the session token.

Only after this final check passes will Safari unlock the payment sheet and allow the user to authenticate the transaction using Touch ID or Face ID.

Continuous Verification

Domain verification is not a one-time event. Apple's servers periodically ping the /.well-known/apple-developer-merchantid-domain-association path on the merchant's server, particularly when the site's SSL/TLS certificate is close to expiring. If the file is removed or becomes inaccessible, Apple revokes the domain's verified status. Consequently, Apple will refuse to generate Merchant Sessions for that domain, and Safari will immediately block the Apple Pay sheet from functioning.