Skip to main content

Embedded Fields — Apple Pay domain setup

Before Apple Pay buttons appear in your checkout, Apple verifies that the domain serving the page is one registered with our payments network — a one-time setup per domain, self-serve from Settings → Wallet Domains in your Von Payments dashboard: add the domain, download its verification file, host the file, click Verify. About five minutes per domain; no Apple Developer account needed to register it — Von Payments holds the Apple Pay registration on your behalf. Google Pay has no file; how its entry works is in How domain entries work.

Apple's verifier fetches https://{your-domain}/.well-known/apple-developer-merchantid-domain-association and compares its bytes with what we registered. If that fetch ever fails — a 404, a TLS problem, changed content — Apple flips the domain back to unverified with no email or alert: buyers simply stop seeing the button.

When you need to set up a domain​

Every distinct hostname where buyers will see the card field — checkout.acmehats.com, pay.acmehats.com, staging.acmehats.com (a separate registration from live). Subdomains are separate domains and Apple Pay supports no wildcards. Behind a CDN, Apple verifies the domain in the buyer's address bar, not the CDN's.

Step-by-step setup​

1. Download the verification file​

In Settings → Wallet Domains, click Add domain, enter the hostname (no https://, no path), choose Apple Pay, then Add domain — or click an existing domain row. On the detail page click Download verification file; your browser saves a single binary file named exactly apple-developer-merchantid-domain-association, no extension, unique to your account-and-domain pair.

Each domain row shows Verified, Pending, Failed or Revoked, and flags a domain whose annual re-check is approaching as Expiring soon.

2. Host the file on your domain​

Serve it at:

https://{your-domain}/.well-known/apple-developer-merchantid-domain-association

The path is exact and case-sensitive. Apple's verifier does not follow redirects, does not accept gzip content-encoding, and does not accept a 200 with HTML — plain raw bytes at exactly this URL over HTTPS with a valid certificate. Any Content-Type works; Apple reads the bytes.

Framework-specific recipes​

Next.js

Drop the file into public/.well-known/apple-developer-merchantid-domain-association. Next.js serves the public/ directory at the site root automatically; no config change.

Vite / Vue / Svelte

Drop the file into public/.well-known/apple-developer-merchantid-domain-association. Vite serves public/ at the site root in both dev and production builds.

Vercel

Hosting any of the framework patterns above on Vercel works out of the box. For static sites without a framework, you can also use a vercel.json rewrite:

{
"rewrites": [
{
"source": "/.well-known/apple-developer-merchantid-domain-association",
"destination": "/_static/apple-developer-merchantid-domain-association"
}
]
}

Cloudflare Pages

Drop the file at the project root path _static/.well-known/apple-developer-merchantid-domain-association (or wherever your build outputs). Cloudflare's static handler serves it directly — no edge function needed.

Cloudflare Workers

Add a route for the well-known path that returns the file content from KV or an env.ASSETS.fetch() lookup:

export default {
async fetch(req: Request, env: Env) {
if (new URL(req.url).pathname === "/.well-known/apple-developer-merchantid-domain-association") {
return new Response(APPLE_PAY_DOMAIN_FILE, {
headers: { "content-type": "application/octet-stream" },
});
}
// ...rest of your worker
},
};

Nginx

location = /.well-known/apple-developer-merchantid-domain-association {
alias /var/www/.well-known/apple-developer-merchantid-domain-association;
default_type application/octet-stream;
}

Apache

Drop the file into your document root at .well-known/apple-developer-merchantid-domain-association. Apache serves dotfile directories by default; if you've disabled that, add:

<Directory "/var/www/html/.well-known">
Require all granted
</Directory>

Express / Node

app.get("/.well-known/apple-developer-merchantid-domain-association", (req, res) => {
res.type("application/octet-stream").send(APPLE_PAY_DOMAIN_FILE);
});

Static site / CDN-only hosting

Most static-site hosts (Netlify, Surge, Render, Render-Cloudflare-R2) serve public/.well-known/ or equivalent without config. If yours doesn't, check the host's docs for "well-known files" or "dotfile directories."

3. Confirm the file is reachable​

curl -v https://{your-domain}/.well-known/apple-developer-merchantid-domain-association

Expect HTTP 200, a non-empty body (a few KB), a valid certificate, and no redirects. Fix any 301 / 302, 404, 403 or TLS error first.

4. Click Verify in the dashboard​

On the domain's detail page click Verify. Von Payments triggers the verification call with Apple and the page polls for the result, usually within 30 seconds:

  • Verified — Apple Pay buttons start working on the buyer's next page load; the SDK picks up the state on the next session retrieve.
  • Failed — the page says why; see Why a check failed.

If the page stops polling while verification is still running, reopen the domain or click Verify again to pick up the result.

5. Keep the file in place​

Apple re-verifies on a rolling annual cycle, and a missing file (a cleanup script, a purged CDN cache, a host that does not serve dotfile paths) flips the domain back to unverified silently. Our daily renewal worker re-runs the verification when the file disappears, but it can only verify what you serve — pin the file in version control and in your deploy pipeline.

Why a check failed​

A failed or pending entry carries one of five reasons. The domain's page shows it as a sentence; the wallet-domains API returns the code as failureReason (failure_reason in Python). The same reasons apply to Apple Pay and Google Pay entries.

failureReasonThe domain's page saysWhat to do
reattest_failedWe couldn't confirm your domain.Apple Pay: re-host the file at the exact path, re-run the curl in step 3, then click Verify (or call verify). Google Pay: click Re-check.
wallet_type_not_configuredApple Pay (or Google Pay) is off for your account, so this domain can't be verified, and your site isn't the problem. The message then says where to turn it on.If the Apple Pay & Google Pay add-on is off, turn it on in Von Pay features first. Then tick the box on the domain's page to agree to the wallet's terms and press Turn on; the domain is re-checked straight away.
no_gateway_accountWallet payments become available once your business is approved and its payment account is connected … your site isn't the problem.Wait for approval; contact support if it is already done.
transient_errorA temporary issue interrupted verification.Try again in a moment.
unknown_failureVerification didn't complete.Try again; contact support if it persists.

What can go wrong​

SymptomLikely causeFix
curl returns 404File not deployed, or path mismatch (extra extension, missing dot, wrong directory)Verify exact path on disk; redeploy
curl returns 301 / 302Web server redirects all paths to https://, www., or trailing-slash versionCarve out an exemption for /.well-known/
curl returns 200 but body is your homepage HTMLSPA catch-all route is intercepting the pathAdd /.well-known/* to the framework's exclude list (Next.js middleware.ts matcher, Vite catch-all config, etc.)
Verification fails again after a redeploy that had workedCI compressed the file with gzip, or transformed it as an assetAdd /.well-known/* to your build's no-transform list
Domain flips back to unverified after working for monthsApple's annual re-check failed because the file is no longer reachableRe-host the file; our renewal job re-runs the verification automatically once the URL works
Apple Pay button still doesn't appear after verificationBrowser caching of the device-eligibility checkTest in a private Safari window; the Apple Pay availability cache clears on session end

Testing your setup​

Once the domain is Verified, use a real Apple device: Safari on macOS (Touch ID, or a paired iPhone) or Safari on iOS. No other browser can render the button. The card in Wallet depends on your key:

  • Test key (vp_pk_test_…): on the device that holds the card (the iPhone, if you pay through a paired one), sign out of iCloud and sign in with an Apple sandbox tester account. Then add one of Apple's test cards to Wallet. You create testers in App Store Connect, which needs an Apple developer account; the cards are in Apple's sandbox testing guide. The device's region must be one where Apple Pay is offered. A real card does not work with a test key: the sheet opens and closes at once, and nothing is charged.
  • Live key (vp_pk_live_…): sign the device back in with your own Apple Account and use a real card in Wallet. The payment charges that card.

Visit your checkout at the registered domain, create a session through the normal integration (Quickstart) and mount the card field: the Apple Pay button appears inside the card mount when the buyer is eligible (eligibility model).

Tap the button, authenticate in the sheet, and elements.submit() resolves with the same two arms as a card in embed mode: charged: true when nothing was saved, or token when the form saves the card (a buyer on the session and the agreement known when the form loads). On a charge-and-save session the tap has already moved the money: a returned token is the vaulted card, not a handle to charge this payment again. Confirm settlement via the webhook before fulfilling.

If the button does not appear, the embed emits no error — it simply does not render. Re-check the domain's status in Settings → Wallet Domains (click Verify again if it is not Verified) and the eligibility gates: Safari on an Apple device with a card in Wallet. If the sheet opens and closes at once with a test key, check that Wallet holds an Apple test card, not a real card (above). Standalone wallet buttons in elements mode report the frame_wallet_* codes instead — Errors → Wallet errors.

What's next​