Prerequisites
Before you start integrating the Apple Pay button, make sure you have the following in place.
What you need
| Artifact | Where to get it |
|---|---|
Apple Pay-enabled terminal (terminalId) | Test-portal / portal → Settings → Online payment methods → Apple Pay: see your terminals, find the terminalId, and toggle Apple Pay on/off per terminal. |
OAuth client credentials (clientId / clientSecret) | Provided by DNA Payments after merchant onboarding |
| HTTPS-enabled web server | Your hosting |
The OAuth credentials are used to generate an access token on your backend: see Authentication for the full flow.
Domain registration (self-service)
Apple requires every domain that hosts the Apple Pay button to be registered. With DNA Payments this is fully self-service: you do not need an Apple Developer account or a support ticket.
| Environment | UI path | Portal URL |
|---|---|---|
| Sandbox / Test | Settings → Online payment methods → Apple Pay → Add new domain | test-portal.dnapayments.com |
| Production | Settings → Online payment methods → Apple Pay → Add new domain | portal.dnapayments.com |
- Domains must match exactly (no
www.prefix unless that is the actual host, no wildcards). Each subdomain has to be registered separately. - Test and production domains live in different portals, so register them independently.
- A missing or mismatching domain is the most common cause of
1003 FAILED_TO_VALIDATE_APPLE_PAY_SESSION. The button itself renders normally; the error surfaces inonErroronly after the user taps it and merchant validation runs against our backend.
- All Apple Pay setup on the Apple side: Merchant ID, certificates, payment processing decryption.
- Apple session validation (
onValidateMerchant) is performed by our backend, not by your front-end.
You only register the domains where the button is rendered. (For sandbox testing you'll need access to App Store Connect to create sandbox tester credentials: see Testing.)
Local development
If you want to run the integration on localhost, you need a public HTTPS URL. The recommended path is ngrok: see Local Testing Setup for the full walkthrough.
With these prerequisites in place, you are ready to move on to Integration.