Skip to main content
Apple Pay is available to cardholders at participating banks in supported countries. For more information, refer to Apple’s participating banks documentation.

​
Payment Method Details

​
Overview

PayNext is registered with Apple as a Platform Integrator. We onboard your domains under our Apple Pay Merchant ID — you don’t need your own Apple Developer account, Apple Pay Merchant ID, or Apple Pay certificates. Setup happens in the Dashboard — enter your domain, host the verification file we provide, and the domain verifies with Apple automatically. Apple Pay buttons render automatically in the PayNext Checkout SDK when the customer’s device supports Apple Pay and your domain is active.
PayNext supports Visa and Mastercard through Apple Pay. Other card networks (Amex, Discover) are not supported.

​
Prerequisites

  • A publicly accessible HTTPS domain where the PayNext checkout is hosted
  • The ability to host a static file under /.well-known/ on that domain

​
Setup

Setup happens entirely in the PayNext Dashboard. Enter your domain, host one verification file, and PayNext verifies the domain with Apple.

​
Step 1: Open the Add domain dialog

1

Open Apple Pay domain settings

In the PayNext Dashboard, go to Checkout → Apple Pay, then click Manage Apple Pay domains.
2

Add a domain

Click Add new domain and enter the bare hostname (e.g., checkout.example.com) — no https://, no path, no port.

​
Step 2: Download and host the verification file

Host the file before you verify the domain — Apple fetches it the moment you add the domain. The file content is identical for every domain you register with us.
1

Download the verification file

In the Add new domain dialog, click Download. The file is named apple-developer-merchantid-domain-association.
2

Host the file

Place the file at this exact URL on each registered domain:
Requirements:
  • Served over HTTPS with a valid TLS certificate
  • Returns 200 OK with the exact file contents — no redirects
  • Content-Type text/plain or application/octet-stream
Place the file in your project’s public/.well-known/ directory. Most static hosting platforms serve files from public/ at the site root automatically.
Host the same file on every domain you register — the content is identical across all your domains under PayNext, but the URL must be reachable on each domain separately.

​
Step 3: Verify the domain

Once the file is live, click Add in the dialog. PayNext registers the domain with Apple under our Platform Integrator account, and Apple fetches the verification file from your domain. The status changes from Pending to Active. Repeat for every domain and subdomain where Apple Pay buttons will appear. If the domain stays Pending or shows an error, verify the file is reachable:
Expected response: HTTP/2 200 with the file contents. Common issues:
  • The URL redirects (Apple does not follow redirects)
  • The file is served over HTTP, not HTTPS
  • The file path is wrong — it must be exactly /.well-known/apple-developer-merchantid-domain-association
  • The file content differs from what the Dashboard provided

​
Token Processing

When a customer authorizes an Apple Pay payment:
  1. The customer authenticates using Face ID, Touch ID, or passcode
  2. Apple generates an EC_v1 encrypted payment token containing a network token and 3DS cryptogram
  3. The PayNext SDK sends the encrypted token directly to the PayNext server
  4. PayNext decrypts the token server-side and verifies its CMS signature against the Apple Root CA - G3 certificate chain
  5. PayNext extracts the network token, expiry, and cryptogram, then routes the payment to your processor
The PayNext SDK handles both transports automatically:
  • Safari (macOS / iOS / iPadOS): Uses the native ApplePaySession API
  • Non-Safari browsers (Chrome, Firefox, Edge on macOS): Uses the W3C PaymentRequest API with iPhone handoff via QR code
Both transports produce identical EC_v1 payment tokens, so the backend processing is the same regardless of browser.

​
Checkout Implementation

The PayNext Checkout SDK handles the entire Apple Pay flow — merchant validation, token acquisition, and browser transport selection. No direct interaction with Apple Pay APIs is required. Apple Pay buttons render automatically when PayNext detects that:
  • The customer’s device supports Apple Pay
  • Your domain is registered and Active in the PayNext Dashboard
You control the checkout experience through configuration passed to the mount method — see Getting Started for the mounting flow and Customize Checkout Behavior for available options.

​
Testing

​
Switch to Sandbox

  1. In the Dashboard, switch the environment to Sandbox using the environment toggle in the bottom-left corner
  2. In the SDK, pass environment: 'sandbox' to the mount method — see Getting Started for details

​
Test requirements

Apple Pay test mode requires a real Apple device or Mac signed in with a Sandbox Tester Apple ID — a regular Apple ID won’t accept Apple’s test cards.
1

Create a Sandbox Tester

In App Store Connect → Users and Access → Sandbox Testers, create a tester account.
2

Sign in on your test device

On a Mac or iOS device, sign out of your regular Apple ID for Wallet and Apple Pay, then sign in with the Sandbox Tester.
3

Add a sandbox card to Wallet

Use one of Apple’s sandbox test cards — never real cards in Sandbox mode.
4

Trigger an Apple Pay checkout

Open the PayNext checkout on your test domain, click the Apple Pay button, and complete authentication.
Ensure the test device’s region and currency match your processor configuration, otherwise Apple Pay will refuse to render the sheet.

​
Verification

  • Confirm the PayNext payment history shows the Apple Pay wallet indicator
  • Verify that Workflows execute as expected (including 3DS cryptogram handling)
  • Test on both Safari and non-Safari browsers (Chrome on macOS) to verify both transports
For processor-specific Apple Pay testing guides, see Stripe’s Apple Pay testing and Braintree’s Apple Pay sandbox docs.

​
Billing Address

When a customer completes payment with Apple Pay, PayNext captures the billing address from the wallet and submits it to the payment processor.

​
3DS and Authentication

Apple Pay handles 3D Secure differently than standard card payments. Authentication is embedded directly in the wallet experience.

​
How it works

  1. First payment (CIT): The customer authenticates using Face ID, Touch ID, or passcode. Apple Pay generates a 3DS cryptogram automatically — no challenge screen appears. This initial establishes the authentication chain for future charges.
  2. Recurring payments (MIT): All subsequent charges use exemptions. The card networks recognize the original CIT authentication and allow off-session payments without additional 3DS.
  3. 3RI not supported: Apple Pay does not support flows. The wallet architecture relies on MIT exemptions rather than re-authenticating for each recurring charge.

​
Resources