Apple Pay Integration Guide

This document covers the end-to-end Apple Pay integration process for merchants using the Global Payments API. It explains what the required certificates are, why they're needed, and what to do with them at each step.

To ensure safe, isolated testing and production operation, merchants should adopt the following structure:

• Use distinct merchant IDs (MIDs): Use one MID for the Sandbox (testing environment) and another for production (live transactions).
• Assign separate payment processing certificates for each MID: This ensures that a certificate used in the sandbox cannot accidentally impact production.
• Create additional MIDs for testing variants (optional): For example, create one MID for 3DS testing, one for wallets only, and so forth. This is recommended for testing under different configurations without affecting baseline flows.

A) Log into your Apple Developer account and click on the Identifiers tab on the top-right corner.
B) Click the plus icon "+" to add a new Apple Pay merchant ID.
C) Use the following format: merchant.com.yourbrand.
D) Save this ID. It will be referenced in certificates and needed for session validation.

2.1. Merchant identity certificate (for session validation)

The merchant identity certificate is necessary to validate Apple Pay sessions in Safari/iOS.

A) Provision the Merchant Identity Certificate:

openssl genrsa -out merchant_id.key 2048
openssl req -new -key merchant_id.key -out merchant_id.csr \
  -subj "/CN=Apple Pay Merchant ID: merchant.com.yourbrand"

B) Log into your Apple Developer account, click on Certificates and then Merchant Identity Certificate to upload the Certificate Signing Request (CSR)
C) Download the resulting merchant_id.cer.
D) Use the OpenSSL code below to convert the merchant ID certificate to .pem file format. This is necessary because Apple Pay’s default .cer file format cannot typically be read by other systems and can create issues.

openssl x509 -in merchant_id.cer -inform DER -out merchant_id.pem -outform PEM

Below, there are two additional, optional steps that you can use if needed. Once you complete Step 1 and 2.1, you’ll have the keys necessary for your backend Apple Pay session validations.

Create a combined file (Optional)

While merchant setup is outside of the scope of Global Payments' API, if your backend requires a combined file, you can use the following step to create it.

cat merchant_id.pem merchant_id.key > merchant_combined.pem

Check your .key and .pem combination (Optional)

This is an optional step that allows you to ensure you’re using the right .key and .pem combination. They should match:

• openssl rsa -noout -modulus -in merchant_id.key | openssl md5
• openssl x509 -noout -modulus -in merchant_id.pem | openssl md5

Both returned values should be identical.

2.2. Payment processing certificate (for token encryption)

Apple Pay requires a payment processing certificate to encrypt the payment token. The certificate owner then uses the same certificate to decrypt the payment token and process the transaction.

There are two options for handling decryption.

Option 1. Global Payments is handling decryption and generates CSR (preferred)

With this option, Global Payments generates the CSR and stores the related private key.

A) Log in to Realcontrol in Sandbox or Production.
B) On the Client Settings tab, navigate to the Apple Pay section. Click the Obtain CSR button to generate and download a new certificate. Note that generating one CSR per client is recommended.
C) Log into your Apple Developer Account and click on the Identifiers tab on the top-right corner.
D) Select Merchant IDs → your Merchant ID → Apple Pay Payment Processing Certificate and upload the CSR you downloaded in Step 2 with this option.
E) Download the .cer file.
F) Return to your Global Payments Portal and upload the .cer file to the Apple Pay section.

Option 2. Merchant is handling decryption and generates the CSR manually

With this option, the whole wallet process occurs outside the Global Payments environment, and we will only receive an Auth request.

A) Use the code below to decrypt the token and generate the CSR.

openssl ecparam -name prime256v1 -genkey -noout -out payment.key
openssl req -new -key payment.key -out payment.csr \
  -subj "/CN=Apple Pay Merchant ID: merchant.com.yourbrand"

B) Log into your Apple Developer account, select Certificates, then Payment Processing Certificate to upload the CSR.
C) Download the payment .cer file.
D) Apple frequently serves .cer files as .der files. So it's best to convert to .pem format if you're going to combine.

openssl x509 -in payment.cer -inform DER -out payment.pem -outform PEM

Apple requires domain verification.

A) Add your domain to the Domain Verification section in your Apple Developer account. Do not use https://. The domain name (e.g., test.com) is all that is expected.
B) Log into your Apple Developer account, select your Merchant ID, then click Add Domain, to access and download the domain verification file.
C) Host the file at the domain location as shown: https://yourdomain.com/.well-known/apple-developer-merchantid-domain-association.
D) Be aware that the file:

• Must be a plain text file (.txt)
• Must be served over HTTPS
• Cannot have any redirects
  E) Once you've checked to make sure your file meets the above requirements, click Verify in your Apple Developer Account.

This step is required for Safari/iOS to activate the Apple Pay session securely.

The following call returns a valid applePaySession that your frontend uses for validation:

requests.post(validation_url, cert=('merchant_id.pem', 'merchant_id.key'), json={
  "merchantIdentifier": "merchant.com.yourbrand",
  "displayName": "Your Store",
  "initiative": "web",
  "initiativeContext": "yourdomain.com"
})

Node.js example

const https = require('https');
const agent = new https.Agent({
  cert: fs.readFileSync('merchant_combined.pem'),
  key: fs.readFileSync('merchant_combined.pem')
});

After the Apple Pay JS returns the token, you send the entire token payload to Global Payments:

{
  "source": {
    "type": "applepay",
    "token": {
      "version": "EC_v1",
      "data": "...",
      "signature": "...",
      "header": { ... }
    }
  },
  "amount": 1000,
  "currency": "EUR",
  "reference": "ORDER-1234"
}

Global Payments uses the previously provided payment processing cert generated in Step 2.2 to decrypt the token and process the payment.

Apple Pay setup verification commands

This guide contains OpenSSL and curl commands to verify:

• Merchant Identity Certificate
• Payment Processing Certificate
• Certificate Signing Request (CSR)
• Apple Pay Domain Association

Change the names, bolded in the commands below, to match your files.

1. Verify merchant identity certificate

To verify the merchant identity certificate, change merchant_id.pem to match your file.

Make sure each certificate is used with the correct AMID: You can verify this using OpenSSL as shown below.

openssl x509 -in ./certs/merchant_id.pem -noout -subject -issuer -serial -fingerprint -enddate

Expected output includes:

• subject=UID=merchant.newdocs.gp, CN=merchant.newdocs.gp
• issuer=Apple Inc.
• Valid serial, fingerprint, and notAfter date

2. Verify payment processing certificate

openssl x509 -in apple_pay.cer -inform DER -out apple_pay.pem -outform PEM
 
openssl x509 -in ./apple_pay.pem -noout -subject -issuer -serial -fingerprint -enddate

Expected output includes:

• subject=UID=merchant.newdocs.gp, CN=Apple Pay Payment Processing:merchant.newdocs.gp
• issuer=Apple Inc.
• Valid serial, fingerprint, and notAfter date

3. Verify CSR (optional)

If using a .csr generated by RealControl or another system:

openssl req -in ./Realex.certSigningRequest -noout -text

Expected output includes:

• Subject: CN=realex payments user
• Public Key Algorithm: id-ecPublicKey
• ASN1 OID: prime256v1

4. Check Apple Pay domain association file

curl -s -o - https://test.org/.well-known/apple-developer-merchantid-domain-association

Expected output:

["merchant.newdocs.gp"]

To check for HTTP 200:

curl -s -o /dev/null -w "%{http_code}" https://test.org/.well-known/apple-developer-merchantid-domain-association

If all of these are true, you should be ready to go:

• You have created an Apple Pay Merchant ID in my Apple Developer account.
• You have generated the Merchant Identity Certificate and uploaded it to Apple.
• You have converted the .cer file to .pem and integrated it into my backend.
• You have provisioned the Payment Processing Certificate via Global Payments or OpenSSL.
• You have hosted the Apple domain verification file and verified ownership.
• You have implemented backend Apple Pay session validation using the correct cert and key.
• You have tested the startSession response from Apple and verified it loads in the frontend.
• You have received a live token from Apple Pay and successfully passed it to Global Payments.
• You have verified that Global Payments processed the token without errors.