Apple Pay Setup Guide

Accept Apple Pay payments on your website with secure, one-tap checkout.

Before You Start

Apple Pay setup requires several steps across multiple systems. This guide will walk you through each one.

Which Setup Method Do You Need?

Setup Method	Best For	Requirements	Time to Complete
Simple Setup	Most merchants	None	~10 minutes
Advanced Setup	Enterprise, custom requirements	Apple Developer Account ($99/year)	~30-60 minutes

Simple Setup (Recommended)

Use this method if you don't have an Apple Developer Account or want the fastest path to accepting Apple Pay.

Step 1: Enable Apple Pay Service

Log in to your Control Panel
Navigate to Settings → Services
Enable Apple Pay Service
A new Apple Pay tab will appear in Settings

Step 2: Register Your Domain

Go to Settings → Apple Pay
Click Add New Certificate
Click Custom Configuration
Enter your website domain(s) — you can add up to 100 domains

Step 3: Verify Your Domain

Critical Step

You must host Apple's verification file on your domain before saving. Apple Pay will not work without this.

Click Download Domain Verification File
Upload this file to your web server at: https://yourdomain.com/.well-known/apple-developer-merchantid-domain-association
Click the test link below each domain to verify the file is accessible
Once all domains pass verification, click Save

Verification File Checklist

[ ] File is accessible via HTTPS (not HTTP)
[ ] File is at the exact path: /.well-known/apple-developer-merchantid-domain-association
[ ] File has no extension (not .txt, not .html)
[ ] File content matches exactly what you downloaded (no modifications)
[ ] Your server returns Content-Type: text/plain or application/octet-stream

Testing the Verification File

Open your browser and navigate to:

https://yourdomain.com/.well-known/apple-developer-merchantid-domain-association

You should see a string of characters. If you get a 404 error or redirect, the verification will fail.

Step 4: You're Done!

Your Apple Pay key will be displayed in the Control Panel. Use this key when integrating Apple Pay into your website (see Integration Examples below).

Advanced Setup

Use this method if you have an Apple Developer Account and need full control over your certificates.

Overview

You'll create two certificates:

Certificate	Purpose	Key Type
Merchant Identity Certificate	Authenticates your server with Apple Pay	RSA 2048-bit
Payment Processing Certificate	Decrypts payment data from Apple	ECC (prime256v1)

Prerequisites

[ ] Active Apple Developer Account ($99/year)
[ ] OpenSSL installed on your computer
[ ] Terminal/Command Line access
[ ] Apple Pay Merchant ID created in Apple Developer Portal

Creating an Apple Pay Merchant ID

Go to Apple Developer Portal
Click the + button to create a new identifier
Select Merchant IDs and click Continue
Enter a description and identifier (e.g., merchant.com.yourcompany.app)
Click Register

Step 1: Create Merchant Identity Certificate

This certificate authenticates your server when communicating with Apple Pay.

1.1 Generate Private Key and CSR

Open Terminal and run this command (replace Your Company Name and US with your details):

bash

openssl req -new -newkey rsa:2048 -nodes \
  -keyout merchant.key \
  -out merchant.csr \
  -subj '/O=Your Company Name/C=US'

This creates two files:

merchant.key — Your private key (keep this secure!)
merchant.csr — Certificate Signing Request (upload to Apple)

1.2 Upload CSR to Apple

Go to Apple Developer Portal → Certificates
Click + to create a new certificate
Select Apple Pay Merchant Identity Certificate
Choose your Merchant ID
Upload merchant.csr
Download the certificate (merchant_id.cer)

1.3 Convert Certificate to PEM

bash

openssl x509 -inform der -in merchant_id.cer -out merchant.crt.pem

1.4 Upload to Control Panel

Navigate to Settings → Apple Pay → Create Advanced
Open merchant.crt.pem in a text editor
Copy everything from -----BEGIN CERTIFICATE----- to -----END CERTIFICATE-----
Paste into the Merchant Certificate field
Open merchant.key in a text editor
Copy everything from -----BEGIN PRIVATE KEY----- to -----END PRIVATE KEY-----
Paste into the Merchant Certificate Key field

Don't Save Yet

Complete Step 2 before saving. You need both certificates.

Step 2: Create Payment Processing Certificate

This certificate decrypts the payment data that Apple sends when a customer pays.

2.1 Generate ECC Private Key

bash

openssl ecparam -out processing.key -name prime256v1 -genkey

2.2 Create CSR

bash

openssl req -new -sha256 -key processing.key -nodes -out processing.csr

When prompted, you can press Enter to accept defaults or enter your company info.

2.3 Upload CSR to Apple

Go to Apple Developer Portal → Certificates
Click + to create a new certificate
Select Apple Pay Payment Processing Certificate
Choose your Merchant ID
Upload processing.csr
Download the certificate (apple_pay.cer)

2.4 Convert Certificate to PEM

bash

openssl x509 -inform DER -outform PEM -in apple_pay.cer -out processing.crt.pem

2.5 Convert Private Key to PEM

Run these three commands in order:

bash

# Step 1: Convert certificate
openssl x509 -inform DER -outform PEM -in apple_pay.cer -out temp.pem

# Step 2: Create PKCS12 bundle (you'll be prompted for a password - remember it)
openssl pkcs12 -export -out processing.p12 -inkey processing.key -in temp.pem

# Step 3: Extract private key as PEM (enter the password from step 2)
openssl pkcs12 -in processing.p12 -out processing.key.pem -nocerts -nodes

# Clean up temp file
rm temp.pem

2.6 Upload to Control Panel

Open processing.crt.pem in a text editor
Copy everything from -----BEGIN CERTIFICATE----- to -----END CERTIFICATE-----
Paste into the Processing Certificate field
Open processing.key.pem in a text editor
Copy everything from -----BEGIN PRIVATE KEY----- to -----END PRIVATE KEY-----
Paste into the Processing Certificate Key field
Click Save

Step 3: Register Your Domain with Apple

In Apple Developer Portal, go to your Merchant ID
Under Merchant Domains, click Add Domain
Enter your domain (e.g., www.yourstore.com)
Download the verification file
Host it at: https://yourdomain.com/.well-known/apple-developer-merchantid-domain-association
Click Verify in the Apple Portal

Integration Examples

Once your certificates are configured, integrate Apple Pay into your checkout page.

Method 1: Using Tokenizer (Simplest)

Our Tokenizer library handles Apple Pay with minimal code:

html

<script src="https://{PAYMENT_PROVIDER_URL}/tokenizer/tokenizer.js"></script>
<div id="payment-container"></div>

javascript

const tokenizer = new Tokenizer({
  url: 'https://{PAYMENT_PROVIDER_URL}',
  apikey: '<YOUR_PUBLIC_API_KEY>',
  container: '#payment-container',
  
  submission: (response) => {
    if (response.status === 'success') {
      // Send token to your server to process payment
      processPayment(response.token)
    } else {
      console.error('Payment failed:', response)
    }
  },
  
  settings: {
    payment: {
      types: ['card', 'apple_pay'],  // Enable both card and Apple Pay
      applePay: {
        key: '<YOUR_APPLE_PAY_KEY>',  // From Control Panel
        version: 5,
        payment: {
          countryCode: 'US',
          currencyCode: 'USD',
          total: { 
            label: 'Your Store Name', 
            amount: '25.00' 
          },
          merchantCapabilities: ['supports3DS']
        },
        autoPay: async (authorizationEvent) => {
          // Process the payment on your server
          const response = await fetch('/api/checkout', {
            method: 'POST',
            body: JSON.stringify(authorizationEvent),
            headers: { 'Content-Type': 'application/json' }
          })
          const result = await response.json()
          return result.success ? 'success' : 'fail'
        }
      }
    }
  }
})

Method 2: Using Apple Pay JS

For more control over the Apple Pay experience:

html

<script src="https://applepay.cdn-apple.com/jsapi/1.latest/apple-pay-sdk.js"></script>

<apple-pay-button 
  buttonstyle="black" 
  type="pay" 
  locale="en-US" 
  onclick="startApplePay()">
</apple-pay-button>

javascript

async function startApplePay() {
  // Check if Apple Pay is available
  if (!window.ApplePaySession || !ApplePaySession.canMakePayments()) {
    alert('Apple Pay is not available on this device')
    return
  }

  // Define the payment request
  const paymentRequest = {
    countryCode: 'US',
    currencyCode: 'USD',
    supportedNetworks: ['visa', 'masterCard', 'amex', 'discover'],
    merchantCapabilities: ['supports3DS'],
    total: {
      label: 'Your Store Name',
      type: 'final',
      amount: '25.00'
    }
  }

  // Create the Apple Pay session
  const session = new ApplePaySession(3, paymentRequest)

  // Handle merchant validation
  session.onvalidatemerchant = async (event) => {
    const merchantSession = await fetch(
      'https://{PAYMENT_PROVIDER_URL}/api/applepay/validatemerchant',
      {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          PKeyCompany: '<YOUR_APPLE_PAY_KEY>',
          ValidationUrl: event.validationURL
        })
      }
    ).then(r => r.json())
    
    session.completeMerchantValidation(merchantSession)
  }

  // Handle payment authorization
  session.onpaymentauthorized = async (event) => {
    // Send payment data to your server
    const result = await fetch('/api/process-apple-pay', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(event.payment)
    }).then(r => r.json())

    session.completePayment({
      status: result.success 
        ? ApplePaySession.STATUS_SUCCESS 
        : ApplePaySession.STATUS_FAILURE
    })
  }

  // Handle cancellation
  session.oncancel = () => {
    console.log('Apple Pay cancelled by user')
  }

  // Start the session
  session.begin()
}

Method 3: Using Payment Request API

The Payment Request API provides a standardized way to handle payments:

javascript

async function startApplePay() {
  if (!window.PaymentRequest) {
    alert('Payment Request API not supported')
    return
  }

  const paymentMethods = [{
    supportedMethods: 'https://apple.com/apple-pay',
    data: {
      version: 3,
      merchantIdentifier: '<YOUR_MERCHANT_IDENTIFIER>',
      merchantCapabilities: ['supports3DS'],
      supportedNetworks: ['amex', 'discover', 'masterCard', 'visa'],
      countryCode: 'US'
    }
  }]

  const paymentDetails = {
    total: {
      label: 'Your Store Name',
      amount: { value: '25.00', currency: 'USD' }
    }
  }

  const request = new PaymentRequest(paymentMethods, paymentDetails)

  // Handle merchant validation
  request.onmerchantvalidation = async (event) => {
    const merchantSession = await fetch(
      'https://{PAYMENT_PROVIDER_URL}/api/applepay/validatemerchant',
      {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          PKeyCompany: '<YOUR_APPLE_PAY_KEY>',
          ValidationUrl: event.validationURL
        })
      }
    ).then(r => r.json())
    
    event.complete(merchantSession)
  }

  try {
    const response = await request.show()
    
    // Process the payment on your server
    const result = await fetch('/api/process-apple-pay', {
      method: 'POST',
      body: JSON.stringify(response)
    }).then(r => r.json())

    await response.complete(result.success ? 'success' : 'fail')
  } catch (error) {
    console.error('Payment failed:', error)
  }
}

Testing Apple Pay

Requirements

Safari browser on macOS or iOS
Apple Pay configured on the device with a test card
HTTPS enabled on your domain (Apple Pay won't work over HTTP)

Apple Pay Sandbox

Create an Apple Sandbox Tester Account
Sign into iCloud on your test device with the sandbox account
Add Apple's test cards to your Wallet

Testing Checklist

[ ] Website loads over HTTPS
[ ] Domain verification file is accessible
[ ] Apple Pay button appears on Safari
[ ] Clicking button opens Apple Pay sheet
[ ] Merchant validation completes successfully
[ ] Test payment processes correctly

Troubleshooting

Domain Verification Issues

Problem	Solution
404 error for verification file	Ensure file is at exact path `/.well-known/apple-developer-merchantid-domain-association` with no extension
Verification file has wrong content	Re-download the file; don't modify its contents
File accessible but verification fails	Check your server isn't adding HTML headers or redirecting the request
"Domain not registered" error	Wait 5-10 minutes after verification; Apple's cache may be stale

Certificate Issues

Problem	Solution
"Invalid certificate" error	Ensure you copied the entire certificate including `-----BEGIN` and `-----END` lines
"Key mismatch" error	The private key must match the certificate; regenerate both if needed
Certificate expired	Certificates expire after 25 months; create new ones in Apple Developer Portal
"Merchant ID not found"	Verify your Merchant ID in Apple Developer Portal matches what you're using

Runtime Issues

Problem	Solution
Apple Pay button doesn't appear	User may not have Apple Pay set up, or you're not on Safari
"Merchant validation failed"	Check your Apple Pay key matches the one in Control Panel
Payment sheet closes immediately	Check browser console for JavaScript errors
"Session timed out"	Complete the payment flow within 30 seconds of starting

Common OpenSSL Errors

Error	Solution
`unable to load private key`	Check you're using the correct key file for that certificate
`no certificate matches private key`	The CSR used to create the certificate must use the same private key
`wrong version number`	Make sure you're using `-inform DER` for Apple's `.cer` files

File Reference

After completing setup, you should have these files:

Simple Setup

File	Location
Domain verification file	`https://yourdomain.com/.well-known/apple-developer-merchantid-domain-association`

Advanced Setup

File	Purpose	Keep Secure?
`merchant.key`	Merchant Identity private key	✅ Yes
`merchant.csr`	Certificate Signing Request	No (can delete after use)
`merchant_id.cer`	Certificate from Apple	No (can delete after conversion)
`merchant.crt.pem`	Converted certificate	No
`processing.key`	Payment Processing private key	✅ Yes
`processing.csr`	Certificate Signing Request	No (can delete after use)
`apple_pay.cer`	Certificate from Apple	No (can delete after conversion)
`processing.crt.pem`	Converted certificate	No
`processing.key.pem`	Converted private key	✅ Yes

Keep Private Keys Secure

Never share your .key or .key.pem files. If compromised, revoke the certificates in Apple Developer Portal immediately.

Apple Pay Setup Guide ​

Before You Start ​

Which Setup Method Do You Need? ​

Simple Setup (Recommended) ​

Step 1: Enable Apple Pay Service ​

Step 2: Register Your Domain ​

Step 3: Verify Your Domain ​

Verification File Checklist ​

Step 4: You're Done! ​

Advanced Setup ​

Overview ​

Prerequisites ​

Creating an Apple Pay Merchant ID ​

Step 1: Create Merchant Identity Certificate ​

1.1 Generate Private Key and CSR ​

1.2 Upload CSR to Apple ​

1.3 Convert Certificate to PEM ​

1.4 Upload to Control Panel ​

Step 2: Create Payment Processing Certificate ​

2.1 Generate ECC Private Key ​

2.2 Create CSR ​

2.3 Upload CSR to Apple ​

2.4 Convert Certificate to PEM ​

2.5 Convert Private Key to PEM ​

2.6 Upload to Control Panel ​

Step 3: Register Your Domain with Apple ​

Integration Examples ​

Method 1: Using Tokenizer (Simplest) ​

Method 2: Using Apple Pay JS ​

Method 3: Using Payment Request API ​

Testing Apple Pay ​

Requirements ​

Apple Pay Sandbox ​

Testing Checklist ​

Troubleshooting ​

Domain Verification Issues ​

Certificate Issues ​

Runtime Issues ​

Common OpenSSL Errors ​

File Reference ​

Simple Setup ​

Advanced Setup ​

Apple Pay Setup Guide

Before You Start

Which Setup Method Do You Need?

Simple Setup (Recommended)

Step 1: Enable Apple Pay Service

Step 2: Register Your Domain

Step 3: Verify Your Domain

Verification File Checklist

Step 4: You're Done!

Advanced Setup

Overview

Prerequisites

Creating an Apple Pay Merchant ID

Step 1: Create Merchant Identity Certificate

1.1 Generate Private Key and CSR

1.2 Upload CSR to Apple

1.3 Convert Certificate to PEM

1.4 Upload to Control Panel

Step 2: Create Payment Processing Certificate

2.1 Generate ECC Private Key

2.2 Create CSR

2.3 Upload CSR to Apple

2.4 Convert Certificate to PEM

2.5 Convert Private Key to PEM

2.6 Upload to Control Panel

Step 3: Register Your Domain with Apple

Integration Examples

Method 1: Using Tokenizer (Simplest)

Method 2: Using Apple Pay JS

Method 3: Using Payment Request API

Testing Apple Pay

Requirements

Apple Pay Sandbox

Testing Checklist

Troubleshooting

Domain Verification Issues

Certificate Issues

Runtime Issues

Common OpenSSL Errors

File Reference

Simple Setup

Advanced Setup