Managed Apple Pay

Managed Apple Pay runs on Tonder's Apple Merchant ID and certificate: you send Tonder your domains, host one verification file, and the Web SDK button (@tonder.io/web-sdk) does the rest. The SDK renders the button, presents Apple's payment sheet, and processes the charge; the transaction lands on /process/ with the same shape as a card payment and fires the same webhooks — your reconciliation does not change.

Before you start: checklist

Almost every Apple Pay problem is setup, not code. Go through these items in order; if something still fails, Troubleshooting by symptom tells you which item it is.

Your Tonder account

• Apple Pay is enabled for your business in each environment you use, sandbox and production. Ask your Tonder contact.
• Nothing to set up with Apple: in this model you don't need an Apple developer account, and Tonder registers your domains. Already have your own Merchant ID? That is Bring Your Own Apple Pay.

Your domains (Web SDK)

• Tonder has every domain that shows the button: production, staging and previews. Each subdomain is its own registration, and the domain that counts is the one in the address bar, not an iframe or CDN host.
• The verification file Tonder sent you is live at https://<your-domain>/.well-known/<file name>, served the way Apple requires.
• If your site filters traffic by country, IP or bot rules, Apple's servers can still reach /.well-known/ — see the ranges to allow.
• Tonder has confirmed both conditions: Apple Pay enabled and domain verified.

Your code (Web SDK)

• The checkout is an HTTPS page at the top level, not inside an iframe.
• You await tonder.init() and render the button only when tonder.isApplePayAvailable().available is true.
• <div id="tonder-apple-pay-button"></div> exists and is empty before mount() runs.
• The button's payment callback is synchronous: no await between the tap and the sheet.
• You read results on events.payment; a decline arrives on on_completed.
• Your card option stays visible next to the button.

How you test

• Safari on a real iPhone, iPad or Mac. The iOS Simulator renders the button and then closes the sheet on tap.
• The device has a card in Wallet, and its region is one where Apple Pay is available (Mexico is). A Mac needs Touch ID, or a nearby iPhone or Apple Watch with Apple Pay set up.
• In sandbox, the device is signed in to an Apple Sandbox Tester account with one of Apple's test cards. Tonder's test cards can't be added to Wallet.
• The shopper's IP, location or VPN doesn't matter. Only their Wallet does.

Step 1: ask Tonder to enable it and register your domains

Not a code step, and the most common reason a correct integration fails in production.

• Tonder handles Apple — in this model you never contact them and you do not need an Apple developer account.
• Your part is sending Tonder the list of domains that will show the button — subdomains count separately — and hosting the verification file Tonder gives you.

Start this step before writing code: it gates everything else. The exact steps and failure modes are in the SDK README.

How to serve the verification file

Apple fetches the file from your server and matches it byte for byte, so the URL has to return the file itself:

Before you tell Tonder the file is live, open the URL and read the response body, not just the status code. A single-page app with a catch-all route answers 200 with index.html, so the URL looks healthy while serving the wrong bytes. Some hosts also hide dot-directories: if yours doesn't serve /.well-known/ by default, configure it.

If your site restricts traffic by country or IP

Apple checks the file from its own servers, outside Mexico. If your site only accepts traffic from Mexico, or a firewall, WAF, CDN or bot rule blocks unknown clients, the file loads fine for you and Apple still can't read it — so the domain never verifies. Allow Apple's domain-verification ranges on /.well-known/:

17.23.4.96/27
17.23.19.0/27
17.23.24.32/27
17.32.139.128/26
17.132.108.64/26
17.140.126.0/26
17.157.32.0/27
17.157.40.128/27
17.157.44.128/27
17.179.144.128/25
17.253.0.0/16

Apple publishes this list in Setting up your server and updates it from time to time; check it there before you configure the rule. Only your team can change this — Tonder isn't in the request path.

Step 2: render the button

Apple Pay is the one flow that does not end in a pay() call. Apple requires the payment sheet to open in the same tick as the tap, so the SDK owns the click, and the result comes back on the events.payment callbacks instead of a returned promise.

Those callbacks are not an Apple Pay-only mechanism — they fire for every method the SDK charges, so one set of handlers covers the whole checkout.

The SDK renders the button into an element you provide. It has to exist before mount() runs, and it stays empty — do not put a button, a label, or an icon inside it:

<div id="tonder-apple-pay-button"></div>

const tonder = createTonder({
  api_key: tonderPublicConfig.api_key,
  environment: 'stage', // switch to 'production' when you go live
  session: { customer: { email: 'ada@example.com' } },
  // Fires for EVERY payment method, not just Apple Pay. With pay() these run
  // alongside the promise it returns; Apple Pay has no promise, so for it
  // these callbacks are the only channel.
  events: {
    payment: {
      on_completed: (transaction) => handleResult(transaction),
      on_error: (error) => showError(error.code),
      on_cancel: () => { /* shopper dismissed the sheet — not an error */ },
    },
  },
});

await tonder.init();

// Ask before you render. The answer is an OBJECT, never a bare boolean:
// { available: true }, or { available: false, code, message }. Reading the
// object itself as a condition would always be truthy — read .available.
const availability = tonder.isApplePayAvailable();

if (availability.available) {
  const button = tonder.create('apple_pay_button', {
    // Called SYNCHRONOUSLY when the shopper taps, so it reads whatever the
    // cart holds at that moment — amount, currency and references can all
    // change after mount without remounting the button. It must not be
    // async: Apple requires the sheet to open in the same tick as the tap.
    payment: () => ({
      amount: 250,
      currency: 'MXN',
      return_url: 'https://merchant.example.com/return',
      client_reference: 'ORD-001',
    }),
  });
  await button.mount();
} else {
  // Do not guess at the reason: only APPLE_PAY_UNSUPPORTED_BROWSER means
  // "offer another method"; the other two codes are yours to fix.
  console.info('Apple Pay hidden:', availability.code, availability.message);
}

When availability is false

Customize the button

Safari draws the control natively, so Apple only allows these keys in customization.apple_pay_button — anything else is ignored:

The SDK reads customization once at createTonder() — changing it means building a new instance and mounting again. The same applies to api_key and session.customer.

Where the button goes in your checkout

Apple Pay earns its conversion lift by letting the shopper skip the card form entirely — so the layout that works is the express one: the button first, a divider, and your other methods underneath, untouched.

Checkout

Business licence$250.00 MXN

or

Credit or debit card

The practices below follow Apple's Human Interface Guidelines:

The mistake to avoid is the replacement: swapping the card button out for Apple Pay strands every shopper it isn't available for. Measured checkouts keep both.

What this guide leaves out — a custom container id and releasing the button on a route change — is in Apple Pay in the SDK README.

Step 3: your reconciliation does not change

Nothing to do. The Apple Pay charge lands on /api/v1/process/ like your card charges, produces a transaction with the same shape, and fires the same webhook. Your existing handler already covers it.

Send client_reference in the button's payment data exactly as you do today and your correlation keeps working. See the Webhooks model.

Troubleshooting by symptom

Enablement and domain verification are separate steps and fail differently: without enablement no button ever renders (APPLE_PAY_NOT_ENABLED); without a verified domain the button renders and the sheet closes (APPLE_PAY_VALIDATION_ERROR). Ask Tonder to confirm both.

Test Apple Pay

The decline row is the one that surprises people: on_completed means the charge reached a final answer, not that the answer was yes.

Apple's sandbox cards, the Sandbox Tester account and the device setup are on the Apple Pay overview. They are the same for both models.

Next steps