Apple Pay

Apple Pay se acepta en la web mediante el botón del Web SDK (@tonder.io/web-sdk). El SDK renderiza el botón, presenta la hoja de pago de Apple y procesa el cargo; la transacción cae en /process/ con la misma forma que un pago con tarjeta y dispara los mismos webhooks — tu conciliación no cambia.

Paso 1: pide a Tonder habilitarlo y registrar tus dominios

No es un paso de código, y es la razón más común por la que una integración correcta falla en producción.

• Tonder trata con Apple — tú nunca los contactas y no necesitas cuenta de desarrollador de Apple.
• Tu parte es enviar a Tonder la lista de dominios que mostrarán el botón — los subdominios cuentan por separado — y alojar el archivo de verificación que Tonder te da.

Empieza este paso antes de escribir código: condiciona todo lo demás. Los pasos exactos y los modos de falla están en el README del SDK.

Paso 2: renderiza el botón

Apple Pay es el único flujo que no termina en una llamada a pay(). Apple exige que la hoja de pago se abra en el mismo tick que el toque, así que el SDK es dueño del clic, y el resultado llega por los callbacks de events.payment en lugar de una promesa devuelta.

Esos callbacks no son un mecanismo exclusivo de Apple Pay — se disparan para todos los métodos que el SDK cobra, así que un solo conjunto de handlers cubre el checkout completo.

El SDK renderiza el botón dentro de un elemento tuyo. Debe existir antes de mount() y debe quedar vacío — no le pongas un botón, un texto ni un icono dentro:

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

const tonder = createTonder({
  api_key: tonderPublicConfig.api_key,
  environment: 'stage', // cambia a 'production' al salir a producción
  session: { customer: { email: 'ada@example.com' } },
  // Se disparan para TODOS los métodos, no solo Apple Pay. Con pay() corren
  // junto a la promesa que devuelve; Apple Pay no tiene promesa, así que aquí
  // estos callbacks son el único canal.
  events: {
    payment: {
      on_completed: (transaction) => handleResult(transaction),
      on_error: (error) => showError(error.code),
      on_cancel: () => { /* el comprador cerró la hoja — no es un error */ },
    },
  },
});

await tonder.init();

// Pregunta antes de renderizar. La respuesta es un OBJETO, nunca un booleano:
// { available: true }, o { available: false, code, message }. Usar el objeto
// como condición siempre sería verdadero — lee .available.
const availability = tonder.isApplePayAvailable();

if (availability.available) {
  const button = tonder.create('apple_pay_button', {
    // Se llama SÍNCRONAMENTE cuando el comprador toca, así que lee lo que el
    // carrito tenga en ese momento — monto, moneda y referencias pueden
    // cambiar después del mount sin volver a montar el botón. No debe ser
    // async: Apple exige que la hoja abra en el mismo tick que el toque.
    payment: () => ({
      amount: 250,
      currency: 'MXN',
      return_url: 'https://merchant.example.com/return',
      client_reference: 'ORD-001',
    }),
  });
  await button.mount();
} else {
  // No adivines la razón: solo APPLE_PAY_UNSUPPORTED_BROWSER significa
  // "ofrece otro método"; los otros dos códigos son tuyos por arreglar.
  console.info('Apple Pay oculto:', availability.code, availability.message);
}

Cuando la disponibilidad es false

Personaliza el botón

Safari dibuja el control de forma nativa, así que Apple solo permite cambiar estas llaves en customization.apple_pay_button — cualquier otra cosa se ignora:

El SDK lee customization una sola vez en createTonder() — cambiarla implica construir una instancia nueva y volver a montar. Lo mismo aplica a api_key y session.customer.

Dónde va el botón en tu cajero

Apple Pay gana su lift de conversión dejando que el comprador se salte el formulario de tarjeta por completo — así que el layout que funciona es el exprés: el botón primero, un divisor, y tus demás métodos debajo, intactos.

Checkout

Licencia comercial$250.00 MXN

o

Tarjeta de crédito o débito

Las prácticas siguientes siguen las Human Interface Guidelines de Apple:

El error a evitar es el reemplazo: cambiar el botón de tarjeta por Apple Pay deja varado a todo comprador para quien no está disponible. Los cajeros que convierten conservan ambos.

Lo que queda fuera de esta guía — un id de contenedor personalizado y liberar el botón en un cambio de ruta — está en Apple Pay en el README del SDK.

Paso 3: tu conciliación no cambia

Nada que hacer. El cargo de Apple Pay cae en /api/v1/process/ como tus cargos con tarjeta, produce una transacción con la misma forma y dispara el mismo webhook. Tu handler existente ya lo cubre.

Envía client_reference en el payment del botón exactamente como hoy y tu correlación sigue funcionando. Ver Modelo de webhooks.

Prueba Apple Pay

La fila del rechazo es la que sorprende: on_completed significa que el cargo llegó a una respuesta final, no que la respuesta fue sí.

Tarjetas de prueba del sandbox

Las tarjetas de prueba de Tonder (4000 0000 0000 0077 y el resto de Casos de prueba de tarjeta) no se pueden agregar a Wallet — el sandbox de Apple solo aprovisiona las credenciales de prueba de Apple. Para abrir una hoja de Apple Pay real en sandbox:

Apple las publica como sus FPAN más recientes (agosto de 2025). Aquí solo se reproducen las redes que Tonder procesa; la lista completa está en Apple Pay sandbox testing.

Visa

Mastercard

American Express — solo se aprovisiona con la región del dispositivo en Estados Unidos o Reino Unido. Si Wallet pide un OTP, escribe 111111.

Siguientes pasos