Apple Pay™

Decrypt and vault Apple Pay™ tokens to route payments to any processor, without locking in your payment credentials.

Apple Pay™ is a digital wallet service that lets customers pay using their Apple devices through biometric authentication (Face ID or Touch ID). When a customer pays with Apple Pay™, their device generates an encrypted payment token containing a network-issued token (DPAN or MPAN) and a one-time cryptogram. That encrypted payload must be decrypted before the underlying payment credentials can be sent to a processor.

Basis Theory acts as the decryption and vaulting layer. When the encrypted Apple Pay™ token arrives, Basis Theory decrypts it using your merchant certificates (or its own), stores the payment credentials securely, and returns a reference you can use to route the payment to any processor through the Basis Theory Proxy. This keeps raw card data out of your systems entirely and lets you switch or route across processors without re-collecting payment information.

Apple Pay™ vs. In-App Purchases

For iOS app developers, Apple Pay™ with Basis Theory is an alternative to Apple's In-App Purchase (IAP) system for physical goods and services. IAP routes payments through Apple's billing infrastructure and deducts a 15-30% platform commission. Apple Pay™ routes payments directly through your chosen processor, keeping the full transaction value in your payment flow.

This distinction only applies to physical goods and services. Digital goods and content sold within an app are subject to App Store guidelines and must use IAP regardless.

Start with a Guide

Accept One-Time Payments (DPAN)

Learn how to accept standard Apple Pay™ payments and route them to your payment processor.

Accept Recurring Payments (MPAN)

Learn how to set up Apple Pay™ for subscriptions, automatic reload, and deferred payments.

Testing Reference

Reference for testing your Apple Pay™ integration without a real Apple Pay wallet.

Overview

Certificate Options

Apple Pay™ requires merchant certificates to decrypt payment tokens. Basis Theory supports two paths:

• Basis Theory-managed certificates: Basis Theory registers and manages the merchant certificates on your behalf. You do not need an Apple Developer Account, and domain verification is handled by Basis Theory. Each tenant can register up to 99 domains.
• Merchant-owned certificates (BYOK): You register your own merchant identifier with Apple, manage your own certificates, and verify your domains directly through the Apple Developer Portal. Basis Theory securely stores and uses your certificates at runtime. This path is required if you need more than 99 domains, want full ownership of your Apple Pay™ credentials, or are migrating an existing Apple Pay™ integration.

The integration flow is identical regardless of which certificate path you choose. The only difference is in the initial configuration and in a few optional parameters passed at runtime.

Token Types

When a customer completes an Apple Pay™ payment, Apple returns one of two token types depending on the payment request configuration and issuer support:

• DPAN (Device Primary Account Number): A device-specific network token that persists on the device. Each transaction generates a new one-time cryptogram, but the DPAN itself is reused across transactions on the same device. Used for standard one-time payments.
• MPAN (Merchant Primary Account Number): A merchant-specific token designed for recurring use. Used for subscriptions, automatic reload, and deferred payments. Requires the payment request to include a recurring or deferred payment configuration, and is subject to issuer and network support.

Your tokenization request returns a type field (dpan or mpan) so your backend knows which kind of token was issued. See Token Types in the API reference for full details.

How Apple Pay™ Works

Adding a Card to Apple Wallet

When a user adds a card to Apple Pay™, the following sequence occurs:

1. Apple Wallet sends the card number (FPAN) and the user's personal information to Apple Servers, which verify the card is supported by looking up BIN tables and forward it to the matching issuer.
2. The issuer validates the card. Apple, acting as the Token Requestor, coordinates with the card network (TSP) to provision a new token.
3. The TSP generates a DPAN for the FPAN. The token and associated keys are returned through the provisioning chain.
4. The issuer generates a CVV key used for authorization and returns all values to Apple Servers.
5. Apple Servers provision the credentials to Apple Wallet, which stores them in the device's Secure Element.

Using Apple Pay™ in a Transaction

When a customer authorizes an Apple Pay™ payment:

1. The device retrieves the DPAN or MPAN previously provisioned during wallet enrollment, generates a one-time cryptogram using the Secure Element, and packages both into an encrypted paymentData object.
2. Your application receives this encrypted payload and sends it to Basis Theory for decryption and vaulting.
3. Basis Theory returns a reference to the stored credentials. Your backend uses that reference to forward the payment to your processor via the Basis Theory Proxy.
4. The processor submits the DPAN and cryptogram to the card network. The card network detokenizes the DPAN to the underlying FPAN and forwards the authorization request to the issuer.
5. The issuer approves or declines the transaction. The response flows back through the network to your application.

Glossary

• FPAN: Funding Primary Account Number. The physical or virtual card number, sometimes just called "PAN".
• DPAN: Device Primary Account Number. A device-specific network token generated from the FPAN. Persists on the device across transactions.
• MPAN: Merchant Primary Account Number. A merchant-specific network token used for recurring or deferred payments.
• BIN: Bank Identifier Number. The first 8 digits of a card number, typically preserved when generating DPANs.
• Apple Pay™ Token: The payment token object issued by the device after biometric authentication. Contains an encrypted DPAN or MPAN and a transaction cryptogram.
• Cryptogram: A one-time cryptographic credential generated per transaction by the Secure Element. It is paired with the DPAN or MPAN and cannot be reused across transactions.
• ECI: Electronic Commerce Indicator. A value embedded inside Apple's encrypted payment payload indicating the authentication result. Basis Theory surfaces it after decryption under authentication.eci_indicator. Used by processors to classify the transaction risk level.
• Secure Element: A certified chip in Apple hardware (iPhone, Apple Watch, etc.) that stores payment credentials.
• TSP: Token Service Provider. An entity registered with EMVCo that issues network tokens. Card networks typically act as TSPs.
• Issuer: The bank or financial institution that issued the payment card to the cardholder.
• Acquirer: The bank or entity that processes payments on behalf of merchants.