Skip to main content

Apple Pay™ FAQ

Answers to the questions we hear most often about accepting Apple Pay™ through Basis Theory.

Choosing a setup​

Should I use the managed setup or BYOK?​

  • Managed: Basis Theory registers your domains under its own Apple merchant identifier and manages the certificates. Web only, with no Apple Developer account needed. Apple limits the merchant identifier registered for your tenant to 99 domains. Follow Setup (Managed).
  • BYOK: you register your own merchant identifier and certificates with Apple and upload them to Basis Theory. Required for iOS apps. Recommended when you expect more than 99 web domains, when you already run Apple Pay™ with your own merchant identifier, or when you want to own your payment credentials. Follow Setup (BYOK).

Both can coexist in one tenant. Basis Theory uses your BYOK certificates only on requests that include merchant_registration_id; every other request uses the managed setup.

Why do iOS apps require BYOK?​

Apple's in-app payments entitlement lists the merchant IDs your app uses, and Xcode has you select them from the merchant IDs created in your developer account. The managed setup registers domains under Basis Theory's own Apple identity, which is not available in your developer account, so the native payment sheet needs a merchant ID you own. The Basis Theory API calls are the same once you have the payment token; see Do I need a separate integration for iOS and web?

Can I move from managed to BYOK later? Will existing tokens stop working?​

Yes, and existing resources keep working. Apple certificates are used to decrypt payloads, to create web sessions and to fetch merchant-token events; Apple Pay™ resources that already exist in your tenant are stored under Basis Theory's own encryption and keep working after you add your own certificates. To switch, complete Setup (BYOK), verify your domains with Apple under your own merchant identifier, and pass merchant_registration_id on session and tokenization requests.

MPANs are the exception. A merchant token associates a payment card, a merchant and a user, and Apple Pay™ issues it when the customer initiates a purchase (Apple Pay Merchant Token Management API). MPANs issued under the managed setup stay tied to Basis Theory's merchant identity and continue to work through the managed setup, but they cannot be re-issued under your merchant identifier without the customer authorizing a new payment.

Can I reuse the merchant ID and certificates I already use with another provider?​

Apple lets you use the same merchant ID and payment processing certificate in multiple websites and apps, across test and production environments (Configuring your environment). Basis Theory needs the payment processing certificate and its private key for the merchant identifier whose domains you verified, plus the merchant identity certificate if Basis Theory creates your web sessions. Basis Theory stores up to two certificate sets per merchant registration, expired ones included, so you can rotate without downtime; delete an expired set before uploading a third.

Why does tokenization fail with "Missing paymentData.header.ephemeralPublicKey"?​

Basis Theory returns 400 with the detail "Missing 'paymentData.header.ephemeralPublicKey'. Cannot derive shared secret without it." A genuine Apple payment token lacks this field only when it was encrypted with an RSA certificate, since Apple's RSA_v1 format carries a wrappedKey instead of an ephemeralPublicKey. If your token is EC_v1, confirm you forward Apple's paymentData object unchanged.

Apple uses ECC encryption in most regions and RSA only where ECC is unavailable due to regulatory concerns (Payment token format reference). Basis Theory can only decrypt tokens encrypted to an EC P-256 payment processing certificate, and Apple's CSR instructions call for an ECC 256-bit key pair, with a different process for China mainland (Create a certificate signing request), so generate the CSR with an EC P-256 key as shown in Setup (BYOK). Only the payment processing certificate uses an EC P-256 key; if Apple's portal rejects your CSR with "Expected RSA(2048)", you are creating a merchant identity certificate instead. If your business operates in China mainland, contact us.

Do I need Basis Theory to generate a CSR?​

No. Apple's process has you create the certificate signing request yourself, upload it in your developer account, and download the issued certificate (Configure Apple Pay). You then upload the certificate and private key to Basis Theory as described in Setup (BYOK). Generate the CSR with an EC P-256 key; an RSA certificate is accepted at upload but tokenization fails with it.

Domains and verification​

Why do I have to host the domain association file? Can it be skipped?​

Apple requires a domain-verification file at https://<domain>/.well-known/apple-developer-merchantid-domain-association on every domain before it is registered, and uses the file that belongs to the identity making the registration (Preparing merchant domains for verification). In the managed setup that is Basis Theory's file; in BYOK it is the file from your own developer account (Configure Apple Pay on the Web). There is no file-less path in either setup. Providers that advertise Apple Pay™ with no domain setup host the checkout page on their own verified domain; the requirement is Apple's and applies to whichever domain shows the button. Apple notes that its servers do not require domain verification in the sandbox environment; the domain still has to be registered on api.test.basistheory.com for sandbox sessions.

Why does domain registration fail when the file is reachable?​

Work through this list:

  • The file is served at the exact path above over HTTPS, and the domain is not behind a proxy or redirect, which Apple does not allow (Configuring your environment).
  • Apple fetches the file, not Basis Theory. If you restrict access, allow the IP ranges Apple lists for domain verification in Setting up your server rather than Basis Theory's addresses.
  • Register the fully qualified domain name only, with no scheme or path. Basis Theory sends the value to Apple unchanged and later matches the session domain against it as an exact string, so example.com and www.example.com are two registrations.
  • Your API key belongs to a Management application with apple-pay:manage. Private and public applications cannot hold this permission.
  • Your tenant is below the 99-domain limit, which Apple enforces. A registration Apple rejects returns 422 "Unable to verify domain" without Apple's reason; if Apple cannot be reached or returns an unexpected error, the response is 503. See Register Domain Address.

Which domains do I need to register when the button is inside an iframe or on partner sites?​

Apple requires every top-level domain and subdomain where you display the Apple Pay™ button to be registered and verified (Configuring your environment). For an embedded checkout that means the domain of the page the customer is on, which is each partner's domain, in addition to any domain of your own that renders the button. Cross-origin iframes are supported from Safari 17 when the iframe carries the allow="payment" attribute (Safari 17 release notes). Apple registers fully qualified domain names (RegisterMerchantRequest).

Platforms onboarding many partner domains hit the 99-domain limit of the managed setup quickly. Setup (BYOK) removes the Basis Theory registration step entirely because domains are verified with Apple under your own merchant identifiers.

What is the 99-domain limit?​

Apple limits each merchant identifier registered through its Web Merchant Registration API to 99 domain names (RegisterMerchantRequest). In the managed setup Basis Theory registers your tenant as one merchant identifier with Apple, so a tenant can hold 99 domains. Deregistering a domain frees its slot, and Register All Domain Addresses replaces the whole list in one call. BYOK domains are verified with Apple under your own merchant identifiers and never count against this limit. See Setup (Managed).

Web, iOS and embedded contexts​

Which merchant identifier do I pass to Apple Pay JS methods in the managed setup?​

Your tenant ID, for both canMakePaymentsWithActiveCard and the newer applePayCapabilities. Apple requires the same identifier that registered your domains (RegisterMerchantRequest), and in the managed setup Basis Theory registers them under your tenant ID. For BYOK, use your own merchant identifier.

Does Apple Pay™ on the web work inside app web views?​

Apple's web guide lists Safari and SFSafariViewController as the iOS contexts that support Apple Pay™ on the web (Apple Pay on the Web). Apple added Apple Pay™ on the web to WKWebView in Safari 13, and notes that script injection APIs such as WKUserScript or evaluateJavaScript disable Apple Pay™ for that view (Safari 13 release notes). In practice, web view wrappers that inject scripts, including common React Native WebView configurations, hit this restriction. For a native app, PassKit with your own merchant identifier through Setup (BYOK) avoids those constraints.

Do I need a separate integration for iOS and web?​

The Basis Theory API calls for tokenization and payment processing are identical. The differences are in the front end: the web flow uses the Apple Pay JS API and requires a session creation step, while the iOS flow uses PassKit and skips session creation entirely. iOS integrations also always require Setup (BYOK).

Why does the session request return 422?​

Basis Theory returns 422 for these reasons:

  • Domain not registered on this tenant (managed setup). The domain must match a domain registered on the tenant whose key you are using, as an exact string. A test API key with a production domain, or the apex when the page is on www, fails this check. In BYOK, Basis Theory relies on Apple's validation of the domain against those verified under your merchant identifier.
  • Apple rejected the session. Basis Theory includes Apple's status message in the 422 detail. Basis Theory sends display_name to Apple as displayName, the canonical store name shown to the customer, which Apple caps at 64 UTF-8 characters (Requesting an Apple Pay payment session); a wrong or truncated store name on the sheet points to that value.
  • Environment mismatch. api.basistheory.com targets Apple's production environment and api.test.basistheory.com targets Apple's sandbox, each with its own merchant registry. See Apple Pay™ Environments.
  • validation_url is not an Apple gateway. The URL must point at an Apple Pay gateway host; anything else returns 422 "The Apple Pay validation URL is not permitted."
  • BYOK without a valid certificate. The merchant registration referenced by merchant_registration_id needs a non-expired merchant identity certificate.

If Apple's servers cannot be reached, the request returns 503 instead.

Testing​

How do I test with Apple's sandbox?​

Register your domains on api.test.basistheory.com, which targets Apple's sandbox environment (Apple Pay™ Environments). Apple's sandbox requires a sandbox tester account created in App Store Connect and Apple's published test cards, and test cards do not work in production (Sandbox testing). See Testing with Apple Pay™ Sandbox.

Apple's sandbox is designed for provisioning cards on a device, not for validating payment transactions. In our experience, sandbox cards return a DPAN even for recurring, automatic reload and deferred requests, so merchant-token behavior cannot be exercised in the sandbox. Build your integration to handle both dpan and mpan, which you need regardless, since Apple returns a DPAN whenever the issuer does not support merchant tokens.

What happens in a Test tenant?​

In a Test tenant, Basis Theory decrypts a real Apple Pay™ token from one of Apple's sandbox cards and stores the actual sandbox card data (DPAN, expiration, cryptogram and ECI), which Retrieve and the Proxy return, so you can forward it to your processor's sandbox. The card object's BIN-derived details, such as brand and funding type, are simulated in Test tenants unless BIN enrichment is enabled; bin and last4 come from the real sandbox DPAN. If you cannot complete a wallet flow in your test environment, Testing without an Apple Pay™ token lets a Private application in a Test tenant create a resource with known values. For how this fits into validating the full payment chain before going live, see Platform Testing.

Tokens and data​

How do I know whether a DPAN or MPAN was returned?​

The tokenization response includes a type field on the apple_pay object with the value dpan or mpan. Your backend should read this field to determine how to route and store the token.

Why did I receive a DPAN after requesting an MPAN?​

A DPAN is returned when the issuer has not implemented MPANs, and MPANs are requested automatically only for recurring, automatic reload and deferred payment types (Merchant tokens). In our experience, Apple's sandbox cards return a DPAN rather than a merchant token, so merchant-token behavior cannot be exercised in the sandbox. The tokenization and payment processing flows are identical regardless of which type is issued; check the type field and handle both cases. See Requesting an MPAN.

Are the bin and last4 from the original card or the device token?​

They come from the DPAN or MPAN, not the original physical card (FPAN). Apple's payment token carries the device-specific account number of the card that funds the transaction (Payment token format reference); Basis Theory derives bin and last4 from that decrypted number, and the FPAN is never sent to Basis Theory. The original card's details, for example to match chargeback alerts from Verifi or Ethoca, cannot be derived from the tokenized data.

Apple exposes a plain paymentMethod.displayName on the payment token, which often includes the card brand and the last four digits of the card, in practice the physical card's rather than the DPAN's, although Apple notes there is no guarantee about its content or format (ApplePayPaymentMethod.displayName). Basis Theory does not process this field. If you need the original last four for display or matching, read it on your front end before tokenizing.

Can I get the cardholder name, billing address or email?​

Not from Basis Theory. The tokenization request takes the Apple Pay™ payment token (apple_payment_data), of which Basis Theory uses paymentData and transactionIdentifier; contacts are not part of it. The payment token is encrypted and the billing and shipping contact data are not (ApplePayPayment). Request them with requiredBillingContactFields and requiredShippingContactFields (requiredBillingContactFields) and read billingContact and shippingContact from the payment on your front end.

Is the DPAN the same for every payment?​

For a given card provisioned on a given device, yes. Apple states that the card issuer creates a unique Device Account Number when a card is added and that each device holds its own (Card provisioning security overview), so adding the card again or on another device yields a different number. Apple describes the account number in the payment token as the device-specific account number of the card funding the transaction (Payment token format reference), and the cryptogram as a one-time code (Apple Platform Security). Basis Theory computes a fingerprint on every Apple Pay™ resource so you can recognize the same wallet card across payments. Test tenants decrypt real sandbox tokens, so the same sandbox card on the same device returns the same DPAN there too. Resources created through Testing without an Apple Pay™ token carry whatever card number you supplied.

What is transaction_id?​

It is Apple's transactionIdentifier, copied unchanged, which Apple describes as a unique identifier for the payment that is suitable for use in a receipt (PKPaymentToken.transactionIdentifier).

When does an Apple Pay™ resource expire?​

By default the resource expires on the card expiration date contained in the decrypted payment data. You can pass expires_at on the tokenization request to expire it earlier. When Apple notifies Basis Theory that an MPAN was unlinked, the resource's status becomes unlinked and it expires 30 days later.

Why don't I see Apple Pay™ resources on the Portal's Tokens page?​

Apple Pay™ resources are stored separately from Tokens and Token Intents, so they do not appear in the Portal's Tokens list or count. Store the id returned at tokenization and use Retrieve to read a resource later. To track resources as they are created, retrieved, updated, unlinked or deleted, subscribe to the apple-pay.* webhook events.

Does the decrypted payload include the PAR or the funding card number?​

No. Apple documents the decrypted payment data as the device-specific account number, card expiration, currency, amount, an optional cardholder name, the device manufacturer identifier, the payment data type, the cryptogram payload, for multi-merchant requests the submerchant authentication responses and, for merchant tokens, the merchant token identifier and metadata (Payment token format reference). There is no funding card number and no payment account reference (PAR) in the payload.

Can I use one Apple Pay™ resource with more than one processor?​

Yes. The Proxy can forward the DPAN or MPAN, expiration, cryptogram and ECI from one resource to any processor that accepts decrypted wallet data. Apple describes the cryptogram as a one-time code (Apple Platform Security), so only the first authorization can carry it; a later charge, at the same or another processor, is a merchant-initiated transaction on the stored credential without a cryptogram, subject to your processor's and the card networks' rules. For durable merchant-initiated payments use merchant tokens; see Can I reuse a DPAN for recurring payments?

Which permissions do I need?​

OperationPermissionApplication type
Create a merchant sessionapple-pay:sessionPublic or Private
Tokenize a paymentapple-pay:createPublic or Private
Retrieve with masked card dataapple-pay:readPrivate
Retrieve with full card dataapple-pay:revealPrivate
Register or deregister domains, manage merchant registrations and certificatesapple-pay:manageManagement
Delete a resourceapple-pay:deletePrivate

See the Apple Pay™ API reference for the permissions on each endpoint.

Charging​

What if the first charge fails?​

Apple describes the cryptogram as a one-time code (Apple Platform Security). Once an authorization attempt reaches the issuer, approved or declined, the cryptogram is spent. Basis Theory stores the cryptogram from the payment you tokenized and cannot produce another, so the customer must authorize again through the Apple Pay™ payment sheet, and you tokenize that new payment, before you can retry. If your processor rejected the request before it reached the issuer, for example with a validation error, you can retry with the same resource. A merchant-initiated charge that references the network transaction ID of a failed first authorization also fails, because the networks require an approved customer-initiated transaction to link against.

What do I send to my processor when the ECI indicator is missing?​

The ECI indicator is optional in Apple's payment data, and when you do receive one you must pass it on to your processor or the transaction fails (Payment token format reference). When Apple omits it, authentication.eci_indicator is absent from the resource. Omit your processor's ECI field in that case rather than sending an empty value. Use a request transform on a pre-configured proxy, or retrieve the resource first and build the request conditionally.

Do I need 3DS for Apple Pay™ payments?​

No separate 3-D Secure authentication is needed. Apple requires supports3DS in the payment request's merchantCapabilities (merchantCapabilities), and the resulting payment data of type 3DSecure already contains an online payment cryptogram and, when present, an ECI indicator, both as defined by 3-D Secure (Payment token format reference). Forward them in your processor's wallet or network-token fields as shown in the implementation guide; processors treat them as the authentication for the transaction, so do not run a separate 3DS challenge on an Apple Pay™ payment unless your processor asks for one.

Can I reuse a DPAN for recurring payments?​

Apple positions merchant tokens (MPANs) as the solution for recurring, deferred and automatic reload payments (Apple Pay Merchant Token Management API), and describes DPANs as specific and unique to the Apple device they reside on (Merchant tokens). Apple requests an MPAN automatically when the payment request uses a recurring, automatic reload or deferred payment type (Merchant tokens); configure one of those and follow Subsequent Charges for the merchant-initiated flow.

How does Basis Theory handle MPAN lifecycle updates?​

Apple delivers merchant token events with a tap-and-pull model: Apple calls your tokenNotificationURL with an event identifier, and the details are retrieved from Apple with that identifier, where they remain available for seven days (Apple Pay Merchant Token Management API). When you set tokenNotificationURL to your Basis Theory endpoint, Basis Theory receives the notification, fetches the event, and updates your MPAN resource. No action is required to keep the resource current. Subscribe to the apple-pay.updated and apple-pay.unlinked webhook events to react in your own systems; an unlinked resource expires 30 days later.

  • Managed: https://api.basistheory.com/apple-pay/<YOUR_TENANT_ID>
  • BYOK: https://api.basistheory.com/apple-pay/<YOUR_TENANT_ID>/merchants/<YOUR_MERCHANT_REGISTRATION_ID>. BYOK merchant tokens are issued under your own Apple merchant identity, so Basis Theory needs your merchant_registration_id to fetch their events.

Deleting an MPAN resource asks Apple to unlink the merchant token first. If Apple rejects the unlink or no longer knows the token, the resource is still deleted. Under BYOK you can also unlink a merchant token yourself through Apple's Merchant Token Management API. See Requesting an MPAN and Delete.

Can I convert existing DPANs to MPANs, or move MPANs to another provider?​

You cannot convert a DPAN into an MPAN. Apple issues a merchant token when the customer initiates a purchase with Apple Pay™ (Apple Pay Merchant Token Management API), so obtaining an MPAN for an existing customer requires a new authorization with a recurring, automatic reload or deferred payment request. Moving depends on your setup. Apple associates a merchant token with the merchant it was issued to, so MPANs issued under the managed setup belong to Basis Theory's merchant identity and cannot be moved. Under Setup (BYOK) they are issued to your merchant identifier and remain yours if you change providers; the new provider needs the token data to charge it and your merchant identity certificate to receive lifecycle events.

Why does my Stripe PaymentIntent or SetupIntent fail with Apple Pay™?​

For PaymentIntents, the currencyCode in your Apple Pay™ payment request and the currency of the PaymentIntent must match, or Stripe declines the transaction. For SetupIntents, the currencyCode must match the default currency of your Stripe account, because a SetupIntent always uses that currency and does not accept a currency parameter. The payment data Apple produces carries the currency and amount the customer authorized (Payment token format reference), so a mismatch cannot be corrected after the fact.

Why does my processor reject the decrypted wallet data?​

Your processor must accept decrypted Apple Pay™ data (DPAN or MPAN, expiration, cryptogram and ECI) in its own wallet or network-token fields. The implementation guide shows the request shape for common processors; for anything else, confirm the field names and any account enablement with your processor. The usual causes of a rejection are:

Last updated on