Bring Your Own Apple Pay
Accept Apple Pay under your own Apple Merchant ID: create the certificate from Tonder's CSR and send the payment token through the Direct API.
With Bring Your Own Apple Pay the payment runs under your Apple Merchant ID. You create it in your Apple Developer account, Tonder generates the certificate request and keeps the private key, and your website or iOS app sends each Apple Pay payment token to Tonder through the Direct API. Tonder decrypts it with your key and processes the charge as a Direct API payment. One Merchant ID and one certificate serve your website and your app alike.
Bring Your Own Apple Pay is enabled on request. Ask your Tonder representative before you start: the certificate exchange in step 2 is coordinated with Tonder's integrations team, and each environment, sandbox and production, is set up separately.
No Apple Developer account, or you want the button this week? Managed Apple Pay runs on Tonder's Merchant ID with no Apple paperwork on your side. The comparison shows both side by side.
Before you start: checklist
- An Apple Developer Program membership, and someone with the Account Holder or Admin role: Apple restricts Merchant IDs, certificates and domains to those roles.
- A working Direct API integration: the token is charged with your API key, from your server.
- Apple Pay enabled on request for your business, in each environment you'll use.
- The domains (web) and the app (iOS) that will show Apple Pay. For web, every domain and subdomain is registered separately in Apple.
- A secure channel agreed with your representative for the certificate request and the certificate. Never send them in the clear.
- A real Apple device for testing. The iOS Simulator can't run Apple Pay, and Apple's sandbox cards work for this model too.
How it works
Apple encrypts every payment token with the public key of your Payment Processing Certificate. Only the matching private key can read it, and that key never leaves Tonder: it is generated with the certificate request in step 2 and stays there. That is why you never see or handle the key, and why a certificate created from any other request can't decrypt your shoppers' payments.
Step 1: create your Merchant ID and register your domains
In Apple Developer go to Certificates, Identifiers &
Profiles → Identifiers, press + and choose Merchant IDs. Give it a description and an
identifier in Apple's reverse-domain form, for example merchant.com.yourstore. The identifier
can't change after creation and never expires; the same one serves your website and
your iOS app, in sandbox and in production.
Inside the Merchant ID, under Domains, add every domain and subdomain that will show Apple
Pay — yourstore.com and checkout.yourstore.com are two entries. Apple hands you its
association file; host it at
https://<your-domain>/.well-known/apple-developer-merchantid-domain-association and verify.
The serving requirements
and Apple's IP ranges
are the same as for Managed Apple Pay; here the file comes from your Apple account and keeps
Apple's fixed name. An iOS app needs no domain.
Give your representative the Merchant ID and the environments you need. Tonder prepares the certificate request for it.
Step 2: create the Payment Processing Certificate from Tonder's CSR
Tonder generates a certificate signing request (CSR) for your Merchant ID and sends it to you over the agreed secure channel. The CSR carries only the public half of a key pair; the private key is created with it and stays with Tonder.
In your Merchant ID, under Apple Pay Payment Processing Certificate, choose Create
Certificate and upload Tonder's CSR. Download the certificate Apple issues, a .cer file.
Send the .cer back over the same channel. It holds no secret — it is the public certificate —
but keeping the exchange on the agreed channel is what guarantees the right file reaches the
right account.
Use Tonder's CSR, not one you generate. A certificate created from your own request pairs
with a key Tonder doesn't have, so every token encrypted for it is unreadable and every payment
fails with EAP001. If Apple already shows a certificate on the Merchant ID, leave it alone and
create a new one from Tonder's CSR.
Step 3: Tonder installs the certificate
Tonder converts the certificate, stores it with its private key, and binds both to your business in that environment. You never see or handle the key, and there is nothing to deploy on your side. Tonder confirms the setup, including the web session configuration, and tells you when sandbox and production are ready. Each environment is configured separately.
Step 4: charge the token through the Direct API
When the shopper confirms the sheet, Apple gives your page or app a payment token. Send it to Tonder from your server with the amount and currency the shopper authorized. Tonder decrypts it under your Merchant ID, checks that amount and currency match what Apple sealed into the token, and processes the charge like any other Direct API payment.
The exact POST /process/ request for the token is shared by your Tonder representative during
onboarding, together with the sandbox setup for this model. This page will carry it as soon as it
is published. Nothing else about your Direct API integration changes: same host, same
Authorization header, same X-Request-Id.
Apple's payment token
What you forward is the paymentData object Apple returns — token.paymentData on the web,
PKPaymentToken.paymentData in an iOS app — exactly as you received it:
| Field | What it is |
|---|---|
version | The encryption scheme Apple used, EC_v1 for the certificates Apple issues today |
data | The encrypted payment data: the device account number, its expiry and the cryptogram |
signature | Apple's signature over the token |
header.ephemeralPublicKey | The one-time key Apple used to encrypt data for your certificate |
header.publicKeyHash | A hash of your certificate's public key, which tells Tonder which key decrypts this token |
header.transactionId | Apple's identifier for this authorization |
Forward it whole and untouched: don't re-encode data, don't drop header fields, and don't reuse
a token — each one is bound to a single authorization. The format is Apple's, documented in the
Payment token format reference.
The response and the webhook are those of a Direct API payment, and
GET /api/v1/transactions/{id}/ stays the source of truth. A decline from the issuer comes back as
a declined transaction, not as an Apple Pay error.
What stays the same
- Webhooks. The charge produces a Direct API transaction and the webhook you already receive. See How webhooks work.
- Correlation. Send
client_referenceandmetadata.external_idas on every payment; they come back on the webhook. See Correlation keys. - Status. Fulfil from
GET /api/v1/transactions/{id}/or the webhook, never from the sheet's success animation.
Keep it running: certificates and renewals
| What | Expires | What to do |
|---|---|---|
| Merchant ID | Never | Nothing |
| Payment Processing Certificate | Every 25 months | Apple emails the Account Holder and Admin ahead of time. Before the date, ask your representative for a new CSR and repeat step 2; Tonder swaps the certificate |
| Domain verification (web) | With your domain's SSL certificate | Renew the SSL certificate before it expires and Apple keeps the domain verified; if it lapses, verify the domain again in your Apple account |
Apple publishes these rules in Maintaining your environment.
Troubleshooting
The codes are the Apple Pay errors Tonder returns for this model.
| What you see | Why | Fix |
|---|---|---|
EAP001 — the token could not be decrypted | The certificate on your Merchant ID wasn't created from Tonder's CSR, or the token was altered, re-encoded or reused | Create a new certificate from Tonder's CSR (step 2); forward paymentData untouched |
EAP002 — no certificate configured for your business | Step 3 isn't complete for that environment | Ask your representative to confirm the environment is ready |
EAP003 — Apple rejected the merchant validation | The domain isn't verified under your Merchant ID, or Apple can't reach it | Check the domain in your Apple account, the serving rules and Apple's IP ranges |
EAP004 — amount or currency mismatch | The amount or currency you sent differs from what the shopper authorized on the sheet | Send exactly the values the sheet showed; a changed cart needs a new authorization |
| Works in sandbox, fails in production | Each environment has its own certificate and enablement | Repeat steps 2 and 3 for production |