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.

Why iOS is not supported

Managed setup relies on Basis Theory's own Apple merchant identifier, which only works for web because Apple validates web merchants server-side during session creation. iOS uses a different validation model: every merchant ID passed to PKPaymentRequest must appear in your app's Merchant IDs Entitlement, and that entitlement can only list merchant IDs registered under the same Apple Developer team that signs the app. Basis Theory's merchant ID cannot be entitled to another team's app, so iOS integrations must register their own merchant ID under their own developer account. Follow Setup (BYOK) to do so.

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.