Apple Pay — Direct (Gateway Merchant Validation)
How to embed an Apple Pay button on your own website using the Gateway's own Apple Pay credentials — no Apple Developer account, Merchant Identifier, or certificates of your own required. This is the setup required for a tailored, Direct-style checkout (as opposed to Hosted, see Digital Wallets Overview).
Web only. This only applies to Apple Pay on the Web — embedding an Apple Pay button in a page viewed in Safari. It cannot be used for a native iOS application.
1. Overview
Normally, embedding Apple Pay on your own site means setting up your own Apple Pay Developer Account, Apple Pay Merchant Identifier, and Payment Processing / Merchant Identity certificates. This guide covers an alternative: using the Gateway's Apple Pay Payment Processing and Merchant Identity certificates, along with a unique Apple Pay Merchant Identifier the Gateway registers for you.
This lets you take Apple Pay payments on your own site as easily as on the Gateway's Hosted Payment Page — without your own Apple Pay Merchant Identifier or certificates.
The browser-side integration steps are identical to using your own Apple Pay credentials. The one difference: instead of your web server sending the Merchant validation request directly to Apple's server, it sends that request to the Gateway, which adds the credentials and forwards it to Apple on your behalf.
2. Configuration
To use the Gateway's Apple Pay credentials, the Gateway must first register your web store's domain name with Apple.
- In the Merchant Management System (MMS), go to Preferences → Digital Wallets.
- Add your store's domain — the domain of the page where the Apple Pay button will appear. You can register multiple domains.
- After entering the domain, a pop-up alerts you that you need to download a Domain Verification File — follow the instructions shown.
- Download the file from the link in the pop-up and place it on your web server, in the
.well-knowndirectory. - Apple must be able to download the file from your web server at that location, or domain registration fails. Don't confirm the change in MMS until the file is actually available — and Apple only supports HTTPS, not HTTP, for this file.
3. Integration — the merchant validation request
In your Apple Pay on the Web JavaScript code, your Apple Pay session's
onvalidatemerchant
event handler normally sends a message to your own server, which requests a payment session
from Apple's server directly.
With the Gateway's credentials, that changes: instead of your server requesting the session from Apple, send a Merchant validation request to the Gateway, and the Gateway forwards it to Apple on your behalf.
3.1 Required fields
| Field | Description |
|---|---|
merchantID | Your Gateway Merchant Account ID used to process the Apple Pay transactions |
process | Must be the literal value applepay.validateMerchant — tells the Gateway this is an Apple Pay merchant validation request |
validationURL | The Apple Pay validation URL, taken from the validationURL property of the ApplePayValidateMerchantEvent received by your onvalidatemerchant handler |
displayName | Optional. ≤64 UTF-8 characters, the canonical store name shown to the cardholder. Must stay consistent — don't include dynamic values like order numbers |
domainName | The domain of your store's website making the Apple Pay request. Must match one of the domains registered in MMS (§2) |
signature | The signature for this Hosted Integration request (see the signing guide) |
The response is an opaque Apple Pay session object — pass it directly to your Apple Pay
session's completeMerchantValidation method.
3.2 Request structure
[
'merchantID' => '000000',
'process' => 'applepay.validateMerchant',
'validationURL' => 'https://apple-pay-gateway-cert.apple.com/paymentservices/paymentSession',
'displayName' => 'Example Merchant name here',
'domainName' => 'exampledomainhere.com',
]
Formatted and signed as application/x-www-form-urlencoded:
displayName=Example+Merchant+name+here&domainName=exampledomainhere.com&merchantID=000000&process=applepay.validateMerchant&validationURL=https%3A%2F%2Fapplepaygatewaycert.apple.com%2Fpaymentservices%2FpaymentSession...<signature appended>
Send the request to your Hosted Integration URL, e.g.:
https://gateway.exampledomainhere.com/hosted/
4. FAQ
Does the connection to the Gateway validation URL require a certificate? No. Unlike Apple's own server validation endpoint, an Apple Pay Merchant Identity SSL Certificate is not used for the request to the Gateway. The request must still be correctly formatted and signed like any other Hosted or Direct Integration request.
Why do I need the Domain Verification File?
Apple needs to verify that the domain you provide belongs to you — it does this by confirming
you have sufficient access to add the Domain Verification File to the .well-known directory
at the root of that domain.
The data required was returned by the Gateway, but the Apple Pay UI opens for a moment
before closing again — what's wrong?
Make sure the Domain Verification File downloaded when the custom domain was added in MMS is
actually available at the specified URL on your web server, and that any new file replaces the
old one. Also check the file hasn't picked up an unwanted extension (e.g. .txt) — this
commonly happens when the file is downloaded from MMS on Windows, which can append an
extension by default.
5. Quick reference
Applies to: Apple Pay on the Web (Safari) only — not native iOS
Setup: MMS → Preferences → Digital Wallets → register domain → download & host DVF at /.well-known/
Validation: onvalidatemerchant → send request to the GATEWAY (not Apple directly)
Required: merchantID, process=applepay.validateMerchant, validationURL, domainName, signature
Optional: displayName (must stay static, no dynamic order numbers)
No cert needed: the request to the Gateway itself needs no Apple SSL certificate — only correct signing
6. Source
Breathepay's "Apple Pay - Gateway Merchant Validation" reference document.