Apple Pay is one of the checkout options customers notice most. When it works, a payment takes a moment. When it does not, the button never appears and nobody tells you why.
Most of the difficulty is in the setup. The pieces are individually simple, but they have to line up: identities, certificates, domains and a handshake between your server and Apple. This article walks through them in order and points out where integrations usually go wrong.
What you need before you start
Before you write code, you need several things in place.
- An Apple developer account that you can use to register your merchant identity.
- A merchant identifier that represents your business for Apple Pay.
- Certificates. Typically one identifies your merchant to Apple during validation, and another is used to protect payment data.
- A payment provider that supports Apple Pay and tells you how it expects to receive the token.
- A secure site. Pages that show the button must be served over HTTPS.
Ask your provider early which of these they set up for you and which you must do yourself. Many providers manage part of the process, which can save time and reduce risk.
The flow, step by step
1. Verify your domain
Apple needs to know that you control the domain where the button appears. You prove it by hosting a verification file at a specific location on your site, then registering the domain in your merchant settings.
This is the most common early failure. The file must be reachable from the public internet, served without redirects and with the right content. Check it from outside your network.
2. Check that the customer can pay
Your page asks the browser whether Apple Pay is available and whether the customer has a card set up. Only show the button when the answer is yes. Showing it to customers who cannot use it is a poor experience.
3. Start a payment session
When the customer taps the button, your page creates an Apple Pay session with the payment details: the amount, the currency, your country and the line items you want the customer to see. The payment sheet opens on their device.
Keep the amount, the currency and the line items accurate. The customer sees exactly what you give Apple.
4. Validate the merchant
This is the step that gives the integration its reputation. The browser tells you it needs a merchant session. Your server then contacts Apple, identifies your business with its merchant identity, and receives a session that proves you are a valid merchant. Your server passes this session to the browser, which completes validation.
Key points:
- It must happen from your server, not from the browser, because it uses your private identity.
- It is tied to your domain, so the domain you send must match the one you verified.
- It has a short lifetime. If the customer waits too long, you will need a new session.
- Errors here are usually about certificates, domains or the way the request is made.
5. Authorize the payment
After the customer approves with their device, you receive an encrypted payment token. It does not contain the card number in a usable form. Send it to your server straight away.
6. Process the token
Your server sends the token to your provider. Depending on the provider, this can be done directly, with the provider handling decryption, or by decrypting it yourself using your payment processing certificate. The first option is simpler and keeps you away from more sensitive data.
The provider returns an approval or decline.
7. Complete the session
Tell the browser whether the payment succeeded or failed, so the payment sheet can show the right result to the customer. Then update your order, as with any payment, only after you have confirmed the outcome on your server.
Where integrations break
The domain file is not reachable. Redirects, access rules and incorrect content all cause validation to fail. Test the file from the outside.
Validation is attempted from the wrong place. Calling Apple from the browser, instead of your server, will fail. Keep the identity on the server.
The domain does not match. The domain you send during validation must be one you registered. This often goes wrong between staging and production.
Certificates are wrong or expired. Keep track of expiry dates. A certificate that lapses quietly breaks checkout.
Sessions time out. If the customer pauses on the sheet, you may need to restart. Handle the failure with a clear message.
The token is mishandled. Sending it to the wrong endpoint or in the wrong format causes declines that look like card problems.
The button appears when it should not. If you skip the availability check, customers see a button that does nothing.
Testing
Test on real devices, in Safari and with real user flows.
- Test with an Apple sandbox account and test cards
- Test your provider's test mode as well, since it adds its own checks
- Test with the wallet empty, to see how you handle no card
- Test a slow customer, to see session expiry
- Test cancellation, so closing the sheet does not leave the order in a strange state
- Test on staging and production separately, since domains differ
Web and in-app are not the same
Apple Pay in a mobile app uses a different set of tools from Apple Pay on the web, even though the customer sees a similar sheet. Merchant validation as described here belongs to the web flow. If you run both, plan them as two integrations that share a provider, and test each one separately. Store the shared pieces, such as your merchant identifier and your provider settings, in one place so that they stay consistent.
Security and privacy
The payment token is designed so that you never handle the card number directly. Keep it that way. Do not log tokens, do not store them longer than needed and restrict who can access the systems that process them. Treat your certificate keys as secrets, store them in a secrets manager rather than in your code repository, and plan for rotation before the certificates expire.
Design details that matter
Apple Pay shortens the form, so make the most of it. Ask for shipping and contact details through the sheet when you need them, so the customer does not fill in a form. Make the button prominent on the product and cart pages if your flow allows it, not only at the end.
Recurring and subscription use needs additional setup and has its own rules.
Where to go next
Apple Pay is one part of a well-built checkout. Our payment gateway integration service covers cards, Apple Pay, wallets and local methods with the failure modes above in mind. If you are building a new storefront or app, our web development team can build the checkout around it. Our payments page gives you the full picture.
