Merchant Onboarding Guide

This section provides a step-by-step walkthrough of the merchant registration and onboarding process with Apple Pay. Merchants using the Server-to-Server integration must complete these steps independently before processing live transactions.

info

The steps and interfaces described in this section are based on the Apple Developer Portal as of the time of writing. Apple may update their platform, click-flow, or requirements at any time. We recommend always referring to the official Apple Pay developer documentation and Apple Developer Portal for the most current information.

1. Enroll in the Apple Developer Program

An Apple Developer account is required to configure Apple Pay. Enroll at https://developer.apple.com/programs/.

• A paid Apple Developer Program membership is required. Apple Pay capabilities require an active Apple Developer Program membership.
• For business integrations, Apple strongly recommends enrolling as an Organization rather than as an Individual.
• The organization enrollment process requires a D-U-N-S number (Dun & Bradstreet). If your company does not have one, you can request it for free — but it may take several business days.
• Individual enrollments are also possible, but organization accounts offer better team management and are preferred for production merchant setups.

Apple Developer Program enrollment page.

tip

If your organization already has an Apple Developer account (e.g. for iOS app development), you can reuse it for Apple Pay. No separate account is needed.

2. Create a Merchant Identifier

A merchant identifier uniquely identifies your business to Apple Pay. It is used across all Apple Pay configurations (certificates, domains, sessions). Create one in the Apple Developer Portal:

1. Sign in to your Apple Developer account.
2. Navigate to Certificates, Identifiers & Profiles → Identifiers.
3. Click the "+" button to register a new identifier.
4. Select Merchant IDs as the identifier type and click Continue.

5. Enter the following information:
   • Description — A human-readable name for this merchant identifier (e.g. "My Shop").
   • Identifier — A unique reverse-domain-style string (e.g. merchant.com.yourdomain.pay). This cannot be changed later.
6. Click Continue and then Register.

After registration, the merchant identifier appears in the list under Identifiers → Merchant IDs.

tip

Choose a merchant identifier that clearly identifies your business and environment. You can create multiple merchant identifiers if needed (e.g. merchant.com.yourdomain.production and merchant.com.yourdomain.sandbox for different environments).

3. Create a Payment Processing Certificate

The Payment Processing Certificate is used by Apple to encrypt the payment data included in the Apple Pay token. Your server uses the corresponding private key to decrypt the token and extract the card data.

|

Generate a CSR (Certificate Signing Request)

A CSR must be generated to obtain the Payment Processing Certificate from Apple. Apple requires an ECC (Elliptic Curve) key for payment processing certificates. The corresponding private key must be securely stored on the server that will decrypt Apple Pay tokens.

Using OpenSSL (recommended for servers):

# Generate an ECC private key (prime256v1 curve)
openssl ecparam -out apple_pay_private.key -name prime256v1 -genkey

# Generate the CSR from the private key
openssl req -new -sha256 -key apple_pay_private.key -out apple_pay.csr \
  -subj "/CN=Your Company Name/O=Your Company Name/C=DE"

Using Keychain Access (macOS):

1. Open Keychain Access → Certificate Assistant → Request a Certificate From a Certificate Authority.
2. Enter your email address and common name.
3. Select "Saved to disk" and choose ECC as the key pair algorithm if available.
4. Save the .certSigningRequest file.

warning

Keep the private key secure. The private key generated alongside the CSR is what allows you to decrypt Apple Pay payment tokens. If the private key is compromised, you must revoke the certificate and create a new one. Never share the private key.

Upload the CSR to the Apple Developer Portal

1. In the Apple Developer Portal, navigate to Certificates, Identifiers & Profiles → Identifiers → Merchant IDs.
2. Select the merchant identifier created in Step 2.
3. Under Apple Pay Payment Processing Certificate, click Create Certificate.

4. Apple will ask: "Will payments associated with this Merchant ID be processed exclusively in China mainland?" — Select No (unless your business processes exclusively in China mainland).
5. Click Continue.
6. Upload the CSR file (.csr or .certSigningRequest) generated in the previous step.
7. Click Continue. Apple will generate and issue the certificate.
8. Download the certificate file (.cer).

Install the certificate on your server

The downloaded .cer file must be installed on the server that decrypts Apple Pay tokens. Combine it with the private key for use in your decryption logic:

# Convert the .cer to PEM format
openssl x509 -inform DER -in apple_pay.cer -out apple_pay_cert.pem

# You now have:
# - apple_pay_cert.pem (public certificate)
# - apple_pay_private.key (private key from CSR generation)
# Both are needed to decrypt Apple Pay payment tokens.

warning

The Payment Processing Certificate expires after 25 months. You must renew it before expiration to avoid service interruption. Apple sends expiry reminders to the account holder's email. When you renew, a new CSR and private key pair must be generated.

4. Create a Merchant Identity Certificate (Web only)

The Merchant Identity Certificate is used for TLS mutual authentication between your server and Apple's servers when creating an Apple Pay session on the web. This certificate is only required for web integrations (Apple Pay on the Web) — it is not needed for in-app (iOS/watchOS) integrations.

info

This certificate is used during the merchant validation step, where your server calls Apple's payment session endpoint to prove it is an authorized merchant. It is not used to decrypt payment tokens — that is handled by the Payment Processing Certificate.

Generate a CSR for the Merchant Identity Certificate

Unlike the Payment Processing Certificate, the Merchant Identity Certificate uses an RSA 2048-bit key:

# Generate an RSA private key
openssl genrsa -out apple_pay_merchant_identity.key 2048

# Generate the CSR
openssl req -new -sha256 -key apple_pay_merchant_identity.key -out apple_pay_merchant_identity.csr \
  -subj "/CN=Your Company Name/O=Your Company Name/C=DE"

Upload and download in the Apple Developer Portal

1. In the Apple Developer Portal, select your merchant identifier.
2. Under Apple Pay Merchant Identity Certificate, click Create Certificate.
3. Upload the RSA CSR file.
4. Download the generated certificate.

Use the certificate for merchant validation

Combine the certificate and private key to use in TLS client authentication when calling Apple's session endpoint:

# Convert to PEM
openssl x509 -inform DER -in merchant_id.cer -out apple_pay_merchant_identity_cert.pem

# Create a combined PEM file (used by many HTTP clients for mutual TLS)
cat apple_pay_merchant_identity_cert.pem apple_pay_merchant_identity.key > apple_pay_merchant_identity_combined.pem

Your server uses this combined certificate when making the POST request to Apple's /paymentSession endpoint during merchant validation.

warning

The Merchant Identity Certificate expires after 25 months. Renew it before expiration to avoid disruptions in merchant validation on the web.

5. Register and Verify Your Domain

Apple requires that all domains displaying the Apple Pay button are registered and verified. This step proves you control the domain where Apple Pay is offered.

1. In the Apple Developer Portal, navigate to Certificates, Identifiers & Profiles → Identifiers → Merchant IDs.
2. Select your merchant identifier.
3. Under Merchant Domains, click Add Domain.
4. Enter your fully qualified domain name (e.g. www.yourshop.com). HTTPS is required.

5. Apple provides a domain verification file (apple-developer-merchantid-domain-association). Download it.

6. Host the file on your web server at the following exact path:

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

7. Return to the Apple Developer Portal and click Verify.

info

Each domain where the Apple Pay button is displayed must be individually registered and verified. This includes:

• Your production domain(s)
• Staging or test domains (if you want to test Apple Pay there)
• Subdomains count as separate domains (e.g. shop.yourdomain.com and www.yourdomain.com require separate verification)

tip

The verification file must be served with the correct MIME type (application/octet-stream or text/plain) and must be accessible without redirects. If verification fails, check that the file is reachable at the exact URL and that no WAF/CDN is blocking Apple's verification request.

6. Complete Onboarding with Our Platform

Once your Apple Developer account, certificates, and domain verification are set up, contact us to complete the onboarding process:

info

No Apple Pay-specific information is required from your side for onboarding. Your Apple Pay merchant identifier and certificates are used only between your server and Apple — our platform does not interact with Apple Pay directly in the Server-to-Server integration.

What we provide to you

Item	Description
API credentials	Your api_key and api_password for OneAPI (if not already configured)
Confirmation	Confirmation that your merchant account is configured and ready for Apple Pay processing

7. Integrate the Apple Pay API on Your Frontend

Once the above steps are complete, integrate the Apple Pay API on your website or app. Below is an overview of the key tasks; for full implementation details, refer to Apple's official documentation.

Web Integration

Follow Apple's Apple Pay on the Web documentation. Key steps:

1. Check Apple Pay availability — Use ApplePaySession.canMakePayments() to verify the customer's device supports Apple Pay.

if (window.ApplePaySession && ApplePaySession.canMakePayments()) {
  // Show Apple Pay button
}

2. Render the Apple Pay button — Use Apple's official button styles per the Human Interface Guidelines.

<apple-pay-button buttonstyle="black" type="buy" locale="en"></apple-pay-button>

3. Create an Apple Pay session — When the customer clicks the button, create an ApplePaySession with your payment request:

const paymentRequest = {
  countryCode: "DE",
  currencyCode: "EUR",
  merchantCapabilities: ["supports3DS"],
  supportedNetworks: ["visa", "masterCard"],
  total: {
    label: "Your Shop Name",
    amount: "25.90"
  }
};

const session = new ApplePaySession(3, paymentRequest);

4. Handle merchant validation — Apple calls onvalidatemerchant. Your server must call Apple's /paymentSession endpoint using the Merchant Identity Certificate (from Step 4):

session.onvalidatemerchant = (event) => {
  // Call your server to request a payment session from Apple
  fetch("/your-server/apple-pay/validate", {
    method: "POST",
    body: JSON.stringify({ validationURL: event.validationURL })
  })
  .then(res => res.json())
  .then(merchantSession => {
    session.completeMerchantValidation(merchantSession);
  });
};

Your server-side validation request to Apple:

curl -X POST <validationURL> \
  --cert apple_pay_merchant_identity_combined.pem \
  -d '{
    "merchantIdentifier": "merchant.com.yourdomain.pay",
    "displayName": "Your Shop Name",
    "initiative": "web",
    "initiativeContext": "www.yourshop.com"
  }'

5. Handle the payment token — After the customer authenticates, Apple returns the encrypted payment token via onpaymentauthorized:

session.onpaymentauthorized = (event) => {
  const token = event.payment.token;
  // Send token to your server for decryption
  // Then send decrypted card data to OneAPI
};

6. Decrypt the token on your server — Use the Payment Processing Certificate private key (from Step 3) to decrypt the PKPaymentToken. Extract the card data (DPAN, expiry, cryptogram) and send it to OneAPI.

iOS / App Integration

Follow Apple's PassKit (Apple Pay and Wallet) documentation. Key differences from web:

• No Merchant Identity Certificate is needed (no web-based merchant validation).
• Use PKPaymentAuthorizationViewController or PKPaymentAuthorizationController.
• Merchant validation is handled automatically by the PassKit framework.
• The PKPaymentToken is returned in the didAuthorizePayment delegate method.

note

The exact steps and interfaces may change as Apple updates their platform. The steps above reflect the process as of the time of writing. Refer to the official Apple Pay documentation for the most current information.

Once your domain is verified, certificates are configured, and your frontend integration is complete, you can process live Apple Pay transactions.