Skip to main content

Apple Pay™ Setup (BYOK)

This setup prepares your tenant to accept Apple Pay™ on your website or iOS app using your own merchant certificates. You register your own merchant identifier and certificates with Apple and upload them to Basis Theory. Requires an Apple Developer account and ongoing certificate maintenance. Complete it once before starting your implementation.

  • Full ownership and control of your payment processing credentials
  • No domain limit — register as many domains as your Apple merchant account allows
  • You are responsible for renewing certificates before they expire (every 25 months)

Recommended for:

  • All iOS app integrations — iOS always requires a registered Apple merchant identifier
  • Platforms managing a large number of merchants or domains beyond the 99-domain limit
  • Platforms where each sub-merchant uses their own Apple Pay™ certificates
  • Merchants migrating an existing Apple Pay™ integration with their own certificates
  • Merchants who require full ownership of their payment credentials

For web-only integrations just getting started, Setup (Managed) is a faster path that requires no Apple Developer account.

1. Complete Apple's Merchant Setup​

Once complete, you will have the merchant identifier and certificates needed for the remaining steps. Follow Apple's documentation to create your merchant identifier, generate your certificates, and verify your domain:

When generating your Payment Processing Certificate CSR, use EC P-256. You will need to provide the CSR yourself — Apple's documentation covers the steps.

Basis Theory only supports EC P-256 certificates. If you operate in China and need RSA support, contact us.
Generating the certificate signing request (CSR)

In case you are having trouble generating the CSRs following Apple's requirements, here are commands that you can copy and paste into your Terminal:

Payment Processing CSR
# 1) Generate private key
openssl ecparam -name prime256v1 -genkey -noout -out applepay_processing.key

# 2) Generate CSR
openssl req -new -sha256 \
-key applepay_processing.key \
-out applepay_processing.csr \
-subj "/CN=Apple Pay Payment Processing"
Merchant Identity CSR
# 1) Generate private key
openssl genrsa -out applepay_merchant_identity.key 2048

# 2) Generate CSR
openssl req -new -sha256 \
-key applepay_merchant_identity.key \
-out applepay_merchant_identity.csr \
-subj "/CN=Apple Pay Merchant Identity"

Once complete, you should have:

  • A Payment Processing Certificate (.cer) and its corresponding private key
  • A Merchant Identity Certificate (.cer) and its corresponding private key (web only)
  • A verified domain registered with Apple (web only)

Convert each .cer file to PEM format before proceeding. The Merchant Identity certificate is only required for web integrations — skip it if you are building iOS-only.

# convert the payment processing certificate
openssl x509 -inform DER -in applepay_processing.cer -out applepay_processing.pem

# convert the merchant identity certificate (web only)
openssl x509 -inform DER -in applepay_merchant_identity.cer -out applepay_merchant_identity.pem

2. Package Your Certificates for Upload​

This produces the Base64-encoded PKCS#12 files that the upload API expects. Basis Theory requires certificates in this format — password-protected and Base64-encoded.

Package the Payment Processing certificate:

openssl pkcs12 -export \
  -inkey applepay_processing.key \
  -in applepay_processing.pem \
  -out applepay_processing.p12 \
  -name "apple-pay-payment-processing" \
  -password pass:<YOUR_SECURE_PASSWORD>

# macOS
base64 -i applepay_processing.p12 | tr -d '\n' > applepay_processing.p12.b64

# Linux
base64 --wrap=0 applepay_processing.p12 > applepay_processing.p12.b64

Package the Merchant Identity certificate (web only):

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

# macOS
base64 -i applepay_merchant_identity.p12 | tr -d '\n' > applepay_merchant_identity.p12.b64

# Linux
base64 --wrap=0 applepay_merchant_identity.p12 > applepay_merchant_identity.p12.b64

3. Register Your Merchant with Basis Theory​

This creates the merchant record Basis Theory uses to look up your certificates at runtime. Create a merchant registration using the Create Merchant Registration API. Requires the apple-pay:manage permission. The merchant_identifier value must match the Merchant ID you registered in Apple's portal.

Create Merchant Registration
curl 'https://api.basistheory.com/apple-pay/merchant-registration' \
  -X 'POST' \
  -H 'BT-API-KEY: <MANAGEMENT_API_KEY>' \
  -H 'Content-Type: application/json' \
  --data '{
    "merchant_identifier": "merchant.com.yourcompany.app"
  }'
Response
{
  "id": "3c367ed4-678d-4b98-9cec-d7eaa0f0c26e",
  "merchant_identifier": "merchant.com.yourcompany.app",
  "created_at": "2025-01-15T10:30:00Z"
}

Save the id — you will use it as the merchant_registration_id in session and tokenization requests.

4. Upload Your Certificates​

Once uploaded, Basis Theory can use your certificates to decrypt payment tokens and initiate merchant sessions. Upload your certificates using the Create Merchant Certificates API, passing the id from step 3 as the merchant_registration_id path parameter.

  • For web integrations, include merchant_certificate_data and merchant_certificate_password, and set domain to the domain you verified with Apple in step 1.
  • For iOS-only integrations, merchant_certificate_data, merchant_certificate_password, and domain can all be omitted.
Upload Certificates
curl 'https://api.basistheory.com/apple-pay/merchant-registration/3c367ed4-678d-4b98-9cec-d7eaa0f0c26e/certificates' \
  -X 'POST' \
  -H 'BT-API-KEY: <MANAGEMENT_API_KEY>' \
  -H 'Content-Type: application/json' \
  --data '{
    "merchant_certificate_data": "<BASE64_ENCODED_MERCHANT_ID_P12>",
    "merchant_certificate_password": "<YOUR_SECURE_PASSWORD>",
    "payment_processor_certificate_data": "<BASE64_ENCODED_PAYMENT_PROCESSING_P12>",
    "payment_processor_certificate_password": "<YOUR_SECURE_PASSWORD>",
    "domain": "shop.example.com"
  }'

Basis Theory supports a maximum of 2 active certificates per merchant registration. See the Apple Pay™ API reference for full details.

Certificate Lifecycle​

Apple Pay™ certificates expire every 25 months. If the Payment Processing Certificate expires, Basis Theory cannot decrypt payment tokens. If the Merchant Identity Certificate expires (web only), session creation will fail and customers will not be able to initiate payments.

Plan ahead: set a reminder 30 days before expiration to generate new certificates and upload them to your merchant registration before the existing ones expire.

Last updated on