Apple Pay domain verification
Before Apple can display the Apple Pay payment sheet on a web page, Apple must confirm that the domain serving that page is authorised to accept Apple Pay. This process is called domain verification.
What you need to do depends on how you've integrated Apple Pay with BR-DGE:
| Integration | Sandbox | Production |
|---|---|---|
| Hosted Payment Page | No action required | No action required |
| Web SDK - Apple Pay Module | Send your domain list to BR-DGE Support | Host the verification file and send your domain list to BR-DGE Support |
Domain verification is per Retail ChannelDomains are registered and verified against a specific Retail Channel. Verifying a domain for one Retail Channel doesn't enable Apple Pay on that domain for any of your other Retail Channels. If you process Apple Pay through more than one Retail Channel, register the domains for each one, including where the same domain is used by several Retail Channels.
Using the REST API directly?This guide covers the BR-DGE Hosted Payment Page and Web SDK. If you're submitting Apple Pay tokens directly through the REST API, learn more at Apple Pay (REST API).
How it works
When a customer taps the Apple Pay button, the browser asks Apple's servers to start a payment session for the current page. Apple only allows the session to start if the page's domain has been registered and verified for the BR-DGE Retail Channel processing the payment.
To verify a domain, Apple requests a verification file from a fixed, well-known location on that domain:
https://<your-domain>/.well-known/apple-developer-merchantid-domain-associationIf the file is reachable and its contents match what Apple expects, the domain is verified.
Apple may re-check this file at any time after the initial verification, so it needs to stay in place for as long as you accept Apple Pay on that domain.
Hosted Payment Page
No action is required.
When you use the BR-DGE Hosted Payment Page, the Apple Pay button is presented on a BR-DGE-hosted domain rather than your own.
BR-DGE handles domain registration and verification with Apple on your behalf, in both Sandbox and Production environments.
Web SDK - Apple Pay module
When you use the Apple Pay Module, the Apple Pay button is rendered on your own checkout pages, so every domain that displays the button must be registered with Apple.
Every fully qualified domain counts separatelyApple verifies each fully qualified domain individually.
example.com,www.example.comandcheckout.example.comare three separate domains, and each must be registered.Wildcard domains (
*.example.com) are not supported.
Sandbox environment
No file hosting is required in the Sandbox; the domains must still be registered.
Step 1: Send your domain list to BR-DGE Support
Contact BR-DGE Support with the following information:
- The Retail Channel(s) the domains should be registered against. If you're testing on more than one Retail Channel, list the domains for each one separately.
- The environment: Sandbox.
- The full list of domains and subdomains you'll test Apple Pay on (for example
dev.example.com,staging.example.com).
Step 2: Wait for confirmation
BR-DGE Support confirms with you once your domains have been registered. You can then start testing, refer to Testing Apple Pay.
Adding test domains laterIf you add a new test environment, send the new domain(s) to BR-DGE Support before you start testing on it. Apple Pay won't initialise on an unregistered domain.
Production environment
Step 1: Request the verification file
Contact BR-DGE Support with the following information:
- The Retail Channel(s) the domains should be registered against. If you'll accept Apple Pay through more than one Retail Channel, list the domains for each one separately.
- The environment: Production.
- The full list of domains and subdomains you'll present Apple Pay on.
BR-DGE Support then sends you the domain verification file, namedapple-developer-merchantid-domain-association.
Step 2: Host the file on every domain
Upload the file, unmodified, so that it's served at the following path on each domain in your list:
/.well-known/apple-developer-merchantid-domain-associationFor example, if you'll accept Apple Pay on www.example.com and checkout.example.com, the file must be available at both:
- https://www.example.com/.well-known/apple-developer-merchantid-domain-association
- https://checkout.example.com/.well-known/apple-developer-merchantid-domain-association
The same file is used for all of your domains. Refer to Hosting requirements below before you deploy.
Step 3: Check the file is publicly reachable
From a network outside your organisation (for example, a mobile connection with no VPN), request the file on each domain:
curl -i https://checkout.example.com/.well-known/apple-developer-merchantid-domain-associationYou should see the following:
- An
HTTP/2 200(orHTTP/1.1 200 OK) status, with no redirect. - A response body that exactly matches the contents of the file you were sent.
Step 4: Let BR-DGE Support know the file is live
Reply to BR-DGE Support to confirm that the file is hosted on all of your domains. BR-DGE then registers the domains with Apple, which triggers Apple's verification check.
Support confirms once verification has succeeded.
Step 5: Leave the file in place
Don't remove the file after verification. Apple may re-check it periodically, and if it can't be retrieved the domain can lose its verified status, which stops Apple Pay working on that domain.
Plan ahead for go-liveComplete domain verification before your production launch date. If you later add a new domain or subdomain, host the file there and contact BR-DGE Support before you enable the Apple Pay button on it.
Hosting requirements
Apple's verification servers request the file automatically, without any credentials. If any of the requirements below aren't met, verification fails.
| Requirement | Details |
|---|---|
| Exact path | The file must be at /.well-known/apple-developer-merchantid-domain-association. Don't add a file extension such as .txt. |
| Unmodified contents | Serve the file exactly as provided. Don't edit, reformat, re-encode or compress its contents. |
| HTTPS with a valid certificate | Serve the file over HTTPS, using a valid certificate issued by a trusted certificate authority and supporting TLS 1.2 or higher. Self-signed certificates aren't accepted. |
Direct 200 response | Return the file with an HTTP 200 status. Don't redirect the request — including http → https or example.com → www.example.com redirects. |
| Public access | The file must be available on the public internet with no access restrictions. It can't sit behind a login, basic auth, VPN, IP allow list or geo-blocking. |
| Not blocked by security tooling | Make sure WAFs, CDNs and bot-protection services don't challenge or block the request, for example with a CAPTCHA or JavaScript challenge. If your security tooling uses allow lists, allow Apple's published Apple Pay server IP addresses. |
| Always available | Keep the file in place for as long as you accept Apple Pay on the domain, including after every deployment, migration or infrastructure change. |
Serving the Apple Pay button from an iFrameIf the Apple Pay button is rendered inside an iFrame, the domain you register must be the parent page's domain: the page the customer sees they're on in their browser's address bar.
Don't register the iFrame's domain.
For example, if your checkout at
www.example.comembeds an iFrame frompayments.example.net, registerwww.example.comand host the verification file there.Refer to the other iFrame requirements in Apple Pay Module - Prerequisites.
Troubleshooting
| Symptom | Likely cause | What to do |
|---|---|---|
The Apple Pay sheet opens and immediately closes, or onerror fires when the session starts. | The domain isn't registered, or verification has failed. | Check that the exact domain shown in the browser address bar is in the list you sent to BR-DGE Support. |
Apple Pay works on www.example.com but not on example.com (or the other way round). | Only one of the two domains is registered. | Host the file on, and register, both domains. |
| Apple Pay worked previously but has stopped. | The verification file has been removed or become unreachable (for example after a redeploy, CDN change or new security rule). | Restore the file and repeat the check in Step 3. Contact BR-DGE Support if Apple Pay doesn't recover. |
| Apple Pay works on one Retail Channel but not another on the same domain. | The domain is only registered for one Retail Channel. | Ask BR-DGE Support to register the domain for the other Retail Channel too. |
| Apple Pay fails when the button is inside an iFrame. | The iFrame's domain was registered instead of the parent pages. | Register the parent page's domain (the one in the customer's address bar) and host the file there. |
The check returns 404. | The file isn't at the exact path, has an extension added, or your server doesn't serve dot-prefixed directories or extensionless files. | Confirm the file name and path, and check that your web server or hosting platform serves the .well-known directory as static files. |
The check returns 401, 403 or a challenge page. | Access controls or security tooling are blocking the request. | Remove restrictions on the path, or allow Apple's server IP addresses. |
The check returns a 301 or 302. | A redirect rule applies to the path. | Exclude the path from redirect rules so it returns 200 directly. |
| The check works internally but not externally. | The domain is only reachable on an internal network or VPN. | Make the file publicly reachable, then repeat the check from outside your network. |
If you're still having trouble, contact BR-DGE Support with the affected domain, the environment, and the output of the curl check from Step 3.
Summary FAQs
Do I need to host the verification file in the Sandbox environment?
No. In the Sandbox you only need to send BR-DGE Support the list of domains you'll test on.
I have more than one Retail Channel. Do I need to verify my domains for each one?
Yes. Domain verification is per Retail Channel, so register your domains for every Retail Channel you'll process Apple Pay through, even if they share the same domain.
Can I use the same file on all of my domains?
Yes. Host the same file, unmodified, on every domain you've registered for Production.
Can I remove the file once my domain is verified?
No. Apple may re-check the file at any time, so it must stay in place for as long as you accept Apple Pay on that domain.
Does my staging environment need the file?
Only if it uses the BR-DGE Production environment. Environments that use BR-DGE Sandbox just need to be included in your Sandbox domain list.
What if BR-DGE Support sends me a new version of the file?
Replace the existing file on every domain with the new version, then repeat the check in Step 3.
Related pages
Updated about 3 hours ago