Decrypt Apple Pay™ Data with Your Own Keys

While our managed certificates offer the fastest integration path for new merchants, you may prefer to manage your own configuration—particularly if you are migrating an established Apple Pay™ setup. Choosing to bring your own processing keys, rather than relying on our default managed encryption, ensures seamless continuity with your existing cryptographic assets. Furthermore, unlike the automated managed flow, this approach grants you direct authority over the domain registration process, allowing you to retain full ownership and granular control over your implementation.

By managing your own keys with Basis Theory, you retain full control over the decryption and tokenization of Apple Pay™ payment data. This "Bring Your Own Key" approach allows you to align your integration with Apple’s recommended security model while maintaining the flexibility to own your data and switch processors without friction.

This guide demonstrates how to generate, configure, and use your own Apple Pay™ encryption keys to securely decrypt and tokenize payment data.

Getting Started

To get started, you will need to create a Basis Theory Account and a TEST Tenant.

Sign Up

Sign In

Be sure to use your work email (e.g., john.doe@yourcompany.com)

Understanding Apple Pay™ Certificates

To manage your own keys effectively, it is critical to understand the two distinct certificates Apple Pay™ uses. Although both are issued by Apple as PKCS#12 (.p12) files, they serve different purposes and are not interchangeable.

1. Merchant Identity Certificate: Used strictly for merchant validation and session creation. It allows your server to authenticate with Apple to start a session before the payment sheet appears.

2. Payment Processing Certificate: Used strictly to decrypt payment tokens. When a customer pays, Apple encrypts the data using the public key from this certificate. The corresponding private key, which you will configure in Basis Theory, is used to decrypt and tokenize that data.

Note: Apple requires Apple-issued certificates. Self-signed certificates are not supported for payment processing.

Before generating your keys, ensure you have the following:

• Apple Developer Account: You must be registered as an Apple Pay™ merchant.
• Downloaded Certificates: You should have both the Payment Processing certificate and Merchant Identity certificate downloaded from the Apple Developer Portal
• Domain Verification File: You must download the apple-developer-merchantid-domain-association file from your Merchant ID configuration in the Apple Developer Portal. This file is required to prove you own the domain where Apple Pay™ will be used.
• Local Private Key: The EC P-256 private key used to generate the Certificate Signing Request (CSR) must be stored securely on your system

Implementation: Preparing Your Keys

To upload your keys to Basis Theory, you must convert the Apple-issued certificates into a password-protected, Base64-encoded PKCS#12 format.

1. Verify Your Private Keys

Apple Pay™ requires an EC P-256 private key. If you generated your private key during the CSR creation process, locate that file (e.g., applepay.key).

Run the following command to verify the key curve is correct:

openssl ec -in applepay.key -text -noout | grep ASN1

Expected Output:

ASN1 OID: prime256v1

2. Convert Certificates to PEM

Apple provides certificates in DER (.cer) format, but OpenSSL requires PEM format for conversion.

Run the following to convert your Merchant Identity certificate:

openssl x509 \
  -inform DER \
  -in ApplePayMerchantId.cer \
  -out merchant_id.pem

Run the following to convert your Payment Processing certificate:

openssl x509 \
  -inform DER \
  -in ApplePayPaymentProcessing.cer \
  -out payment_processing.pem

3. Create the PKCS#12 Files

You must now combine the signed certificates (merchant_id.pem and payment_processing.pem) and your private key (applepay.key) into a single .p12 file. This file must be password protected.

openssl pkcs12 -export \
  -inkey merchant_private_key.key \
  -in merchant_id.pem \
  -out merchant_id.p12 \
  -name "apple-pay-merchant-identity"
  -password pass:YOUR_SECURE_PASSWORD

openssl pkcs12 -export \
  -inkey payment_processing_private_key.key \
  -in payment_processing.pem \
  -out payment_processing.p12 \
  -name "apple-pay-payment_processing"
  -password pass:YOUR_SECURE_PASSWORD

Important: When prompted, enter a strong password. You will need to provide this password to Basis Theory to allow the platform to decrypt the certificate data.

4. Base64 Encode the File

The Basis Theory API expects the certificate files as a Base64-encoded string.

base64 -i payment_processing.p12 | tr -d '\n' > payment_processing.p12.base64

base64 -i merchant_id.p12 | tr -d '\n' > merchant_id.p12.base64

5. Upload to Basis Theory

Once you have the encoded string and your password:

• Create an Apple Pay™ merchant registration via the Basis Theory API.
• Upload the payment_processing.p12.base64 and merchant_id.p12.base64 content as the merchant_certificate and provide the password.

5.1 Create your merchant registration

A merchant represents your Apple Pay™ merchant identifier and serves as the root configuration for certificates and tokenization.

Request

cURL

curl --request POST \
--url https://api.basistheory.com/apple-pay/merchant-registration \
--header 'BT-API-KEY: <API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
  "merchant_identifier": "merchant.com.yourcompany.app"
}'

Node

await client.applePay.merchant.create();

C#

await client.ApplePay.Merchant.CreateAsync(new ApplePayMerchantRegisterRequest());

Python

client.apple_pay.merchant.create()

5.2 Upload your merchant registration certificates

Once a merchant is registered, merchant-owned encryption certificates can be associated with it and will be used to decrypt and tokenize Apple Pay™ payment data during tokenization requests.

Request

cURL

curl --request POST \
--url https://api.basistheory.com/apple-pay/merchant-registration/3c367ed4-678d-4b98-9cec-d7eaa0f0c26e/certificates \
--header 'BT-API-KEY: <API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
  "merchant_certificate_data": "MIIHgjCCBmqgAwIBAgIIZ... (Base64 encoded .p12)",
  "merchant_certificate_password": "super_secure_password_123!",
  "payment_processor_certificate_data": "MIIEfTCCA2WgAwIBAgIUE... (Base64 encoded .p12)",
  "payment_processor_certificate_password": "another_secure_password_456$",
  "domain": "shop.example.com"
}'

Node

await client.applePay.merchant.certificates.create("merchantId", request: ApplePayMerchantCertificatesRegisterRequest = {})

C#

await client.ApplePay.Merchant.Certificates.CreateAsync("merchantId",
new ApplePayMerchantCertificatesRegisterRequest()
);

Python

client.client.apple_pay.merchant.certificates.create(
merchant_id="merchantId",
merchant_certificate_data="",
merchant_certificate_password="",
payment_processor_certificate_data=""
)

Request Parameters

Attribute	Required	Description
merchant_certificate_data	true	A base64-encoded, encrypted P12 file containing both the certificate and the private key used to encrypt payment data for the merchant.
merchant_certificate_password	true	The password used to decrypt the merchant_certificate_data. AES-256-CBC with PBKDF2 is used to decrypt the certificate data.
payment_processor_certificate_data	true	A base64 encoded P12 file with encryption. This P12 file should contain both the cert and the private key used for identifying the payment processor. Will use AES-256-CBC with PBKDF2 to decrypt the certificate data.
payment_processor_certificate_password	true	The password used to decrypt the payment_processor_certificate_data.
domain	true	The domain associated to the certificates

Detailed API steps for this upload can be found in the Apple Pay™ API documentation.

Usage: Decrypting Tokens

Once your keys are registered, you must explicitly tell Basis Theory to use them during transactions.

If you haven't already set up the Apple Pay™ button on your site, follow the Configure Apple Pay section first, then return here to decrypt and tokenize payment data with your own encryption keys.

Session Creation

When creating an Apple Pay™ session (using your Merchant Identity Certificate), you must pass your unique merchant_registration_id in the request. This ensures the session is associated with your specific merchant configuration.

Request

cURL

curl --request POST \
--url https://api.basistheory.com/apple-pay/session \
--header 'BT-API-KEY: <API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
  "validation_url": "https://apple-pay-gateway.apple.com/paymentservices/paymentSession",
  "display_name": "My Ecommerce Store",
  "domain": "my-site.example.com",
  "merchant_registration_id": "3c367ed4-678d-4b98-9cec-d7eaa0f0c26e"
}'

Node

await client.applePay.session.create({});

C#

await client.ApplePay.Session.CreateAsync(new ApplePaySessionRequest());

Python

client.apple_pay.session.create()

Request Parameters

Attribute	Required	Description
validation_url	false	Validation URL returned from the onvalidatemerchant event. Default: https://apple-pay-gateway.apple.com/paymentservices/paymentSession
display_name	true	A string of 64 or fewer UTF-8 characters containing the canonical name for your store, suitable for display. A good display name remains a consistent value for the store and doesn't contain dynamic values such as incrementing order numbers. Don’t localize the name. Use only characters from the supported character sets in the fonts listed in the table below.
domain	true	The fully qualified domain name of the website requesting the Apple Pay™ session.
merchant_registration_id	false	The unique identifier of the merchant registration created through the Basis Theory Merchant API.

Detailed API steps for session creation can be found in the Apple Pay™ API documentation.

Tokenization

When the user completes a payment and you receive the encrypted payload from Apple, pass the merchant_registration_id with your tokenization request.

Basis Theory will use the corresponding private key stored in your registration to decrypt the payment data using AES-256-CBC encryption and tokenize it.

Request

cURL

curl --request POST \
--url https://api.basistheory.com/apple-pay \
--header 'BT-API-KEY: <API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
  "expires_at": "2030-12-25",
  "apple_payment_data": {
    "paymentData": {
      "data": "SGVsbG8gV29ybGQ...",
      "signature": "MIAGCSqGS...",
      "header": {
        "transactionId": "a57f68c420bf0230e2b99fbb72828f3af6c827c9f0e2b93dce252cbc12345678",
        "publicKeyHash": "1bDMpis1k/LZ5VasMFBG/JCplfiWDIhtOFaKtGm12345",
        "applicationData": "e7e892097db9bbdd3c0109a5e735b7aff5b5ba9d9d0cd754b7495bdd124d6789",
        "ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE..."
      },
      "version": "EC_v1"
    },
    "paymentMethod": {
      "displayName": "Visa 4242",
      "network": "Visa",
      "type": "credit"
    },
    "transactionIdentifier": "13jNasniq2ABC123DEF456GHI789"
  },
  "merchant_registration_id": "3c367ed4-678d-4b98-9cec-d7eaa0f0c26e"
}'

Node

await client.applePay.create();

C#

await client.ApplePay.CreateAsync(new ApplePayCreateRequest());

Python

client.apple_pay.create()

Request Parameters

Attribute	Required	Description
expires_at	false	An optional expiration date for the token. If blank, defaults to the expiration date in the decrypted Apple Payment data.
apple_payment_data	true	The Apple Pay™ token from the onpaymentauthorized event.
merchant_registration_id	false	The unique identifier of the merchant registration created through the Basis Theory Merchant API.

Detailed API steps for tokenization can be found in the Apple Pay™ API documentation.

Preparing for Production

This checklist will guide you through the critical steps you need to follow before moving your custom Apple Pay™ integration into production. Since you are managing your own private keys and certificates, ensuring that your credentials are valid and your payment processing is correctly configured is essential to prevent processing interruptions.

Certificate Lifecycle Management

Unlike a managed integration, you are responsible for monitoring the expiration dates of your Apple Pay™ certificates.

• Payment Processing Certificate: Expires every 25 months. If this expires, you will be unable to decrypt payment data.
• Merchant Identity Certificate: Expires every 25 months. If this expires, your customers will not be able to start an Apple Pay™ session on your site.

Action Item: We strongly recommend establishing an internal process or setting calendar alerts 30 days prior to expiration to generate new keys and update your Basis Theory configuration without downtime.

Verify Domain Association

Because you are bypassing the managed domain registration, you must ensure your domain is properly verified directly with Apple. This requires hosting a specific verification file on your server.

• Get the File: In your Apple Developer Account, select your Merchant ID and look for the "Merchant Domains" section. Click "Add Domain" to download the apple-developer-merchantid-domain-association file.
• Host the File: Upload this file to your server so it is publicly accessible at https://<YOUR_DOMAIN>/.well-known/apple-developer-merchantid-domain-association.
• Verify: Once hosted, return to the Apple Developer Account and click "Verify". Apple’s servers will check this URL to confirm your ownership.

Test in Production with a Live Wallet

Before going live, perform test transactions using a Live Apple Pay™ wallet with a personal or corporate card added. This step ensures that your specific EC P-256 private key is correctly decrypting payloads in the production environment. Keep in mind that Apple Pay™ in production does not behave the same as in testing, so using live payment information is critical.

Final Notes

Keep logs of your test transactions in production for future reference. Double-check all API keys, certificate expirations, and environment configurations to avoid common production issues.

By choosing to bring your own keys, you have gained full control over your Apple Pay™ identity and domain registration. However, this comes with the added responsibility of maintaining your credentials. Ensure you have a strategy in place for key rotation to avoid service interruptions.

If you encounter issues specific to key importation or decryption, don't hesitate to contact Basis Theory's support team on our Community or via email at support@basistheory.com

By following this checklist, you'll be prepared to seamlessly integrate and go live with your custom Apple Pay™ configuration, providing a secure and smooth payment experience for your users.