English

Português

English

Português

Appearance

Domain configuration for Apple Pay ​

To enable Apple Pay in your store, you must serve the .well-known/apple-developer-merchantid-domain-association file at the root of every domain where the payment button will be shown.

Required in every integration model

This step is required even if you install the Appmax app via the AppStore (integrated model, with a client_id/external_id per store). What changes between models is only who registers the domain with Apple — you always publish the .well-known file yourself. See Apple Pay payment for the full flow and the distinction between models.

What is this file for? ​

Apple requires this file as part of its domain verification process. It proves that Appmax is authorized to process Apple Pay payments on the domains you inform.

Apple uses this file to validate that the domain is correctly linked to the Merchant ID configured by Appmax. Without it, the "Pay with Apple Pay" button won't work in production — the PaymentSheet won't open, or domain validation fails on every transaction attempt.

The .well-known file is not the Apple Token

The Apple Token is the tokenized card, generated per transaction (see Apple Pay payment). The .well-known file is static, the same on every domain, tied to Appmax's merchantIdentifier — not to the transaction.

1. File content ​

Save the text below to a file named apple-developer-merchantid-domain-association (no extension). It is the same content for every domain in your implementation:

7b2276657273696f6e223a312c227073704964223a2238383637324534354136323336423032384645463731323938334343354338354339334633353231433430374142313338414543354144434641334330334442222c22637265617465644f6e223a313735323630333939333937337d

Copy it exactly as is

The content is validated by Apple — one extra space or line break invalidates the domain verification.

2. Publish the file on each domain ​

The file must be published at the following path on each domain where Apple Pay will be used, without renaming it:

https://<store-domain>/.well-known/apple-developer-merchantid-domain-association

Examples:

  • https://domain1.com/.well-known/apple-developer-merchantid-domain-association
  • https://domain2.com/.well-known/apple-developer-merchantid-domain-association
  • https://store3.com/.well-known/apple-developer-merchantid-domain-association

3. Verify accessibility ​

After publishing the file, confirm it's accessible:

bash
curl -I https://<store-domain>/.well-known/apple-developer-merchantid-domain-association

The expected response should contain:

  • HTTP/2 200 OK (or HTTP/1.1 200 OK)
  • Content-Type: text/plain
  • No redirects (neither 301/302 from http to https, nor from www to the root domain or vice versa)

4. Registering the domain with Apple ​

Once the file is published and accessible, how the domain gets registered with Apple depends on your integration model:

  • Integrated model (AppStore installation): registration is done by Appmax, via API, as soon as the domain is informed during app installation (the domain_name or domain_names parameter). The file just needs to already be published by then.
  • Direct flow: you register the domain yourself, in the Apple Developer portal, under your own Apple account. Apple validates the .well-known file at registration time.

In both cases, if the store's domain changes, the new domain is treated as a new one — republish the .well-known file on it and register it again (no need to create a new merchant).

Best practices ​

  • HTTPS is mandatory: the domain must respond only over a secure connection.
  • Avoid redirects: the URL must respond directly with a 200 status, without going through www, an http→https redirect, or any other redirect before reaching the file.
  • Don't change the file's content: its internal hash is validated by Apple.
  • Content-Type: serve the file as text/plain.
  • Suggested Cache-Control: public, max-age=3600.

If you have questions, contact Appmax technical support.