Apple Pay Payment Gateway: How to Accept Apple Pay on Your Website
Accepting Apple Pay on a website takes four things from Apple, not one: a Merchant ID, a Payment Processing Certificate, a Merchant Identity Certificate, and a verified domain. Apple documents all four. The Merchant ID never expires; the Payment Processing Certificate expires every 25 months, and when it lapses silently, live checkouts stop working. Everything below follows Apple’s own configuration documentation.
This page is for the developer or technical lead doing the integration. It does not explain how a payment gateway works in general, and it compares no providers. For authorization, capture and settlement, read our guide to how a payment gateway works. For SAMA licensing and mada certification, read payment gateways in Saudi Arabia.
What is Apple Pay actually doing to a card payment?
Apple Pay is a tokenisation and authentication layer over a card the customer already holds. It does not store a balance, and it is not a funding source. When a customer pays, a device-specific token stands in for the card number, and the transaction settles against the underlying card exactly as a normal card payment would.
That distinction explains most of the behaviour merchants find confusing. Authorization goes to the same issuer and routing follows the same card. Chargeback rights sit with the same cardholder agreement, and nothing about the money movement changes.
What changes is the data your server receives. Instead of a PAN typed into a form, you get an encrypted payment token that your provider must decrypt before authorization, and the customer authenticates on their own device.
What does Apple require before Apple Pay will run on your website?
Apple’s “Configuring your environment” documentation sets out four prerequisites for Apple Pay on the web. You register a Merchant ID, create a Payment Processing Certificate, create a Merchant Identity Certificate, and register and verify every domain that will display the Apple Pay button. Miss any one and the button will not appear.
Each does a different job, and merchants routinely confuse the last two.
- Merchant ID: ties your Apple Pay configuration together in your Apple Developer account. Created once, referenced by everything else.
- Payment Processing Certificate: its paired private key decrypts the payment token. This is the one that touches money.
- Merchant Identity Certificate: a web-only TLS client certificate that authenticates your server to Apple when it requests a merchant session. It decrypts nothing.
- Domain registration and verification: repeated for every domain and subdomain that renders the button.
Apple also publishes Apple Pay Acceptable Use Guidelines for Websites, which govern what you may sell and how you present the button. Read them before you build. The full requirement list sits on Apple’s Configuring your environment page.
How does domain verification work, and why does it fail?
Apple verifies that you control a domain by fetching a file you place on it. The file must sit at exactly https://[DOMAIN]/.well-known/apple-developer-merchantid-domain-association, with no file extension, served over HTTPS. Apple’s verification servers must be able to reach it directly. Domain verification is not required in the sandbox environment.
One documented constraint catches most teams: a registered domain cannot sit behind a proxy or a redirect. If a CDN rule, a WAF or a trailing-slash redirect stands between Apple and that path, verification fails, and the error will not tell you which one did it.
If a CDN rule, a WAF or a trailing-slash redirect stands between Apple and that path, verification fails, and the error will not tell you which one did it.
Three checks resolve most failures. Request the file with an HTTP client that follows no redirects, and expect a 200 with the file body rather than a 301 or a login page. Confirm the response is served as a file, not rewritten by a framework router into HTML. Confirm you registered the exact host that renders the button, because www.example.com and example.com are two registrations. Apple’s reference is Preparing merchant domains for verification.
Which Apple Pay credentials expire, and when?
Apple’s account documentation is explicit about lifetimes, and the answer is not uniform. The Merchant ID never expires. The Payment Processing Certificate expires every 25 months. The Merchant Identity Certificate and your domain verification also expire and require renewal. A merchant who treats all four as permanent will eventually take an outage.
| Artefact | Expires? | Documented lifetime | What breaks when it lapses | Who usually holds it |
|---|---|---|---|---|
| Merchant ID | No | Permanent | Nothing. | Merchant’s Apple Developer account |
| Payment Processing Certificate | Yes | Every 25 months | Tokens can no longer be decrypted. Live payments fail at authorization. | Merchant or PSP (the private key must sit with whoever decrypts) |
| Merchant Identity Certificate (web only) | Yes | Expires and requires renewal | Merchant session requests to Apple fail, before a payment is ever attempted. | Merchant’s web server, or PSP if it hosts the session endpoint |
| Domain verification | Yes | Expires and requires renewal | Apple Pay stops rendering on the affected domain. | Merchant (the file lives on the merchant’s server) |
Twenty-five months is an awkward interval. It is long enough that the engineer who created the certificate has usually changed teams, and it aligns with no annual review cycle, so it never lands in a yearly compliance sweep. The certificate lapses without anyone noticing, and live payments stop.
Treat renewal as an operational task with an owner, not a developer memory. Put the date in the calendar that holds your TLS renewals, set the reminder at 60 days rather than 7, and record who can re-issue it. If your provider holds the private key, get written confirmation that they monitor the expiry.
Who decrypts the Apple Pay token, you or your provider?
The payment token Apple returns is encrypted and must be decrypted before it can be sent for authorization. The private key paired to the Payment Processing Certificate performs that decryption. It is held either by the merchant or by the merchant’s payment provider, and whoever holds it is the party that must be able to process the token.
Put the question to any provider before you sign. Do you decrypt Apple Pay tokens, and do you hold the private key, or do I? Both models exist and both work. If the provider holds it, your integration is simpler and your PCI scope narrower, because decrypted card data never touches your servers. If you hold it, the key management, renewal, and storage obligations are yours. If a provider cannot say which model applies to your account, it is not ready to process your Apple Pay traffic.
Does Apple Pay work with mada in Saudi Arabia?
Yes. SAMA’s official mada page lists adding a mada card to the Apple Pay wallet among mada’s services, and describes biometric authentication and tokenisation as the mechanism. That statement comes from the regulator, not from a bank help page. Apple Pay launched in Saudi Arabia on 19 February 2019.
According to Mastercard’s launch release and contemporaneous reporting by 9to5Mac, Saudi Arabia was the first market where Apple Pay launched through a national scheme covering local banks and international networks at once. That structure is why mada support was there from day one.
Apple Pay changes how the credential is presented, not which network carries it.
For a Saudi merchant, a customer paying with a mada card in Apple Pay is making a mada transaction, with mada’s routing and economics, rather than a separate “Apple Pay” payment type. Your provider still needs Mada acceptance certified through Saudi Payments, and SAMA’s Mada page describes Mada e-commerce as running over 3-D Secure. Apple Pay changes how the credential is presented, not which network carries it.
Why do Apple Pay refunds confuse customers?
Because Apple Pay is a tokenisation layer rather than a wallet holding a balance, a refund has nowhere to go except the underlying card. Money returns to the card that funded the payment, on that card’s normal refund timeline. Apple publishes no separate refund SLA for Apple Pay, and there is no Apple-side balance to credit.
The resulting support ticket is a common one. A customer paid with Apple Pay, you processed the refund, and they see nothing in the Wallet app. The Wallet transaction list is issuer-populated and is not the authoritative record, so a refund can be complete while that view still shows only the original charge.
Tell customers where to look before they ask. Point them to the card statement or the issuing bank’s app, name the card that funded the payment, and say plainly that Apple Pay held no money. We could locate no published SAMA, Saudi Payments, or card-scheme refund-timeline standard for Apple Pay or Mada, so do not quote a number you cannot source. Let the issuer supply the timing.
How do you test Apple Pay before going live?
Sandbox and production differ in one way that repeatedly wastes a launch day: domain verification is not required in the sandbox. A sandbox integration that works perfectly proves nothing about whether your production domain will verify, because that check was never performed there. Plan the cutover accordingly.
Verify the production domain early so proxy and redirect problems surface while there is time to fix them. Confirm the certificate in use is the production one. Then run a small-value live transaction and a live refund against it, on a real device, before announcing anything.
What breaks most often, and how do you fix it?
Four failure modes account for most Apple Pay support tickets on the web, each with a different signature: the button not rendering, domain verification failing, an expired certificate, and sandbox configuration reaching production. The order in which you check them matters, because the symptoms overlap and the error messages rarely name the real cause.
| Symptom | Most likely cause | What to check first |
|---|---|---|
| Apple Pay button does not render at all | The domain rendering the button is not a registered, verified domain | Confirm the exact host, including subdomain, is registered and served over HTTPS, and that the test device has a card in Wallet on a supported browser. |
| Domain verification fails | A proxy, CDN rule or redirect stands between Apple and the association file | Fetch the association file with redirects disabled. Expect a 200 and the raw file, not a 301 or HTML. |
| Button renders, sheet opens, payment fails at authorization | Payment Processing Certificate expired, or the wrong key is in use | Check the certificate expiry against the 25-month lifetime. Confirm the private key held by your PSP matches the certificate. |
| Merchant session request fails before the sheet opens | Merchant Identity Certificate expired or misconfigured on the server | Check the TLS client certificate presented by your session endpoint and its expiry. |
| Works in test, fails in production | Sandbox credentials or an unverified production domain | Remember domain verification is skipped in sandbox. Verify the production domain independently. |
Keep a runbook listing your Merchant ID, every registered domain, both certificate expiry dates, and who can re-issue each one. It fits on one page, and it prevents most repeat incidents.
How do you enable Apple Pay through HyperPay?
HyperPay supports Apple Pay alongside Mada, Visa, Mastercard, American Express, STC Pay, UnionPay, Tabby, Tamara, SADAD and PayPal. The Apple-side work stays with you, because the Merchant ID, domain registration, and association file attest to your control of your own domain. Endpoints and parameters are in the HyperPay integration guide.
The acceptance product itself is described on the HyperPay payments page.
One regulatory point is invisible in Apple’s documentation. Apple sets the technical conditions for accepting Apple Pay and says nothing about who may settle the resulting funds into a Saudi merchant’s bank account. Under SAMA Circular 46004436, in force since 24 July 2024, merchant contracting, KYC and AML checks and final settlement into merchant accounts must be performed by a SAMA-licensed institution or a bank, while a purely technical linkage provider needs no licence. HyperPay appears on SAMA’s register as an Electronic Money Institution under Unified No. 7016872546. Check it yourself on the public register of licensed payment service providers.
If the certificate and domain work above is what stands between you and an Apple Pay button, talk to the HyperPay integration team and get the provider-side configuration done alongside it.
Frequently asked questions about Apple Pay Payment Gateway
Do I need my own Apple Developer account to accept Apple Pay on my website?
Yes. The Merchant ID, the Payment Processing Certificate, and the domain registrations are created in an Apple Developer account, and Apple requires domain verification to prove you control the site displaying the button. Your payment provider can hold the certificate’s private key and decrypt tokens, but the Apple-side registrations remain in your account.
How often does the Apple Pay Payment Processing Certificate need renewing?
Apple documents a 25-month lifetime for the Payment Processing Certificate. The Merchant ID itself never expires, but the Merchant Identity Certificate and your domain verification also expire and need renewal. Set a calendar reminder at least 60 days before each expiry, and record who is able to re-issue the certificate.
Why is my Apple Pay domain verification failing?
Apple requires the association file at exactly /.well-known/apple-developer-merchantid-domain-association over HTTPS, and registered domains cannot sit behind a proxy or redirect. Fetch the path with redirects disabled and confirm you receive a 200 with the raw file. Also confirm you registered the exact host, since www and apex are separate registrations.
Do mada cards work with Apple Pay in Saudi Arabia?
Yes. SAMA’s official mada page lists adding a mada card to the Apple Pay wallet as a mada service, describing biometric authentication and tokenisation. Apple Pay launched in Saudi Arabia on 19 February 2019. A Mada card in Apple Pay produces a Mada transaction, so your provider still needs Mada acceptance certified through Saudi Payments.
Where does an Apple Pay refund go?
To the card that funded the payment. Apple Pay holds no balance, so the refund follows the underlying card’s normal timeline and appears on the card statement or in the issuing bank’s app. The Wallet app’s transaction list is issuer-populated and is not the authoritative record, so it may not show the refund straight away.
Can I test Apple Pay without verifying my domain?
In Apple’s sandbox environment, yes: domain verification is not required there. That is precisely why a working sandbox integration tells you nothing about production readiness. Verify your production domain early, before the release date, so proxy and redirect problems appear while there is still time to correct the server configuration.