Skip to main content

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, Apple's limit for the merchant identifier Basis Theory registers for you
  • 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 limits the merchant identifier Basis Theory registers for your tenant to 99 domains. Every fully qualified domain name counts, so example.com and www.example.com use two slots. Once the limit is reached, registration fails with a 422 "Unable to verify domain" response even when the association file is in place. Deregister domains you no longer use to free slots, or move to Setup (BYOK) if you expect to keep growing.

Registration targets the Apple Pay™ environment that matches the Basis Theory environment you call: api.basistheory.com registers the domain with Apple's production environment, and api.test.basistheory.com registers it with Apple's sandbox environment for testing with Apple sandbox devices. See Apple Pay™ Environments.

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.

FAQ​

Questions about domain verification, iframes, the 99-domain limit, certificates and switching between setups are answered in the Apple Pay™ FAQ.

Last updated on