Apple Pay™ Setup (Managed)

This setup prepares your tenant to accept Apple Pay™ on your website. Basis Theory registers your merchant identifier and manages all certificates on your behalf — no Apple Developer account required. Complete it once before starting your implementation.

• No certificate generation, renewal, or rotation — Basis Theory handles it
• Up to 99 domains per tenant
• Fastest path to get started

Recommended for:

• Direct merchants accepting Apple Pay™ on their own website
• Platforms managing a limited number of sub-merchants (within the 99-domain limit)
• New web integrations without existing Apple Pay™ certificates

If you are building an iOS app, managing many merchants or domains, you need an Apple Developer account — follow Setup (BYOK) instead.

Web: Register Your Domain

Apple verifies domain ownership before allowing merchant sessions to be initiated from a website. You need to host a verification file and register the domain with Basis Theory.

1. Host the domain association file.

Download the file from:

https://cdn.basistheory.com/.well-known/apple-developer-merchantid-domain-association

Serve it at the following path on your domain, accessible over HTTPS:

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

2. Register the domain with Basis Theory.

Register your domain using the Customer Portal or the Register Domain Address API. Requires the apple-pay:manage permission.

Register Domain

curl 'https://api.basistheory.com/apple-pay/domain-registration' \
  -X 'POST' \
  -H 'BT-API-KEY: <MANAGEMENT_API_KEY>' \
  -H 'Content-Type: application/json' \
  --data '{
    "domain": "shop.example.com"
  }'

The domain association file must be publicly accessible before you call the registration endpoint. The API call triggers Apple's verification request — if the file is not in place, registration will fail.

Domain registration is instant. Once registered, the domain is ready to use in Apple Pay™ session requests from your web implementation.

Apple requires HTTPS, which can make local development difficult. Cloudflare Tunnel is a practical option for testing a local server over a public HTTPS URL during development.