Bring Your Own Apple Pay
Acepta Apple Pay con tu propio Merchant ID de Apple: crea el certificado con el CSR de Tonder y envía el token de pago por la API Direct.
Con Bring Your Own Apple Pay (tu propio Merchant ID) el pago corre bajo tu Merchant ID de Apple. Lo creas en tu cuenta de Apple Developer, Tonder genera la solicitud de certificado y conserva la llave privada, y tu sitio web o tu app iOS envía cada token de pago de Apple Pay a Tonder por la API Direct. Tonder lo descifra con tu llave y procesa el cargo como un pago de la API Direct. Un solo Merchant ID y un solo certificado sirven para tu sitio y para tu app.
Bring Your Own Apple Pay se habilita bajo solicitud. Habla con tu representante en Tonder antes de empezar: el intercambio de certificados del paso 2 se coordina con el equipo de integraciones de Tonder, y cada ambiente, sandbox y producción, se configura por separado.
¿No tienes cuenta de Apple Developer, o quieres el botón esta misma semana? Managed Apple Pay corre sobre el Merchant ID de Tonder, sin trámites con Apple de tu lado. La comparativa muestra los dos modelos lado a lado.
Antes de empezar: lista de verificación
- Una membresía del Apple Developer Program, y alguien con el rol de Account Holder o Admin: Apple reserva los Merchant IDs, certificados y dominios a esos roles.
- Una integración de API Direct funcionando: el token se cobra con tu llave API, desde tu servidor.
- Apple Pay habilitado bajo solicitud para tu negocio, en cada ambiente que vayas a usar.
- Los dominios (web) y la app (iOS) que mostrarán Apple Pay. En web, cada dominio y subdominio se registra por separado en Apple.
- Un canal seguro acordado con tu representante para la solicitud de certificado y el certificado. Nunca los envíes en claro.
- Un dispositivo Apple real para probar. El Simulador de iOS no puede correr Apple Pay, y las tarjetas de prueba de Apple también sirven para este modelo.
Cómo funciona
Apple cifra cada token de pago con la llave pública de tu Payment Processing Certificate. Solo la llave privada correspondiente puede leerlo, y esa llave nunca sale de Tonder: se genera junto con la solicitud de certificado del paso 2 y se queda ahí. Por eso nunca ves ni manejas la llave, y por eso un certificado creado con cualquier otra solicitud no puede descifrar los pagos de tus compradores.
Paso 1: crea tu Merchant ID y registra tus dominios
En Apple Developer ve a Certificates, Identifiers &
Profiles → Identifiers, pulsa + y elige Merchant IDs. Dale una descripción y un
identificador con la forma de dominio invertido de Apple, por ejemplo merchant.com.tutienda.
El identificador no puede cambiar después de crearlo y nunca expira; el mismo sirve
para tu sitio web y tu app iOS, en sandbox y en producción.
Dentro del Merchant ID, en Domains, agrega cada dominio y subdominio que mostrará Apple Pay
— tutienda.com y checkout.tutienda.com son dos entradas. Apple te entrega su archivo de
asociación; publícalo en
https://<tu-dominio>/.well-known/apple-developer-merchantid-domain-association y verifica.
Los requisitos para servirlo
y los rangos de IP de Apple
son los mismos que en Managed Apple Pay; aquí el archivo viene de tu cuenta de Apple y conserva
el nombre fijo de Apple. Una app iOS no necesita dominio.
Dale a tu representante el Merchant ID y los ambientes que necesitas. Tonder prepara la solicitud de certificado para él.
Paso 2: crea el Payment Processing Certificate con el CSR de Tonder
Tonder genera una solicitud de firma de certificado (CSR) para tu Merchant ID y te la envía por el canal seguro acordado. El CSR solo lleva la mitad pública de un par de llaves; la llave privada se crea junto con él y se queda en Tonder.
En tu Merchant ID, en Apple Pay Payment Processing Certificate, elige Create Certificate
y sube el CSR de Tonder. Descarga el certificado que Apple emite, un archivo .cer.
Envía el .cer de vuelta por el mismo canal. No contiene ningún secreto — es el certificado
público — pero mantener el intercambio en el canal acordado es lo que garantiza que el archivo
correcto llegue a la cuenta correcta.
Usa el CSR de Tonder, no uno que generes tú. Un certificado creado con tu propia solicitud va
emparejado con una llave que Tonder no tiene, así que cada token cifrado para él es ilegible y cada
pago falla con EAP001. Si Apple ya muestra un certificado en el Merchant ID, déjalo en paz y crea
uno nuevo con el CSR de Tonder.
Paso 3: Tonder instala el certificado
Tonder convierte el certificado, lo guarda junto con su llave privada y asocia ambos a tu negocio en ese ambiente. Nunca ves ni manejas la llave, y no hay nada que desplegar de tu lado. Tonder confirma la configuración, incluida la de la sesión web, y te avisa cuando sandbox y producción están listos. Cada ambiente se configura por separado.
Paso 4: cobra el token por la API Direct
Cuando el comprador confirma la hoja de pago, Apple entrega a tu página o tu app un token de pago. Envíalo a Tonder desde tu servidor con el monto y la moneda que el comprador autorizó. Tonder lo descifra bajo tu Merchant ID, comprueba que monto y moneda coinciden con lo que Apple selló en el token y procesa el cargo como cualquier otro pago de la API Direct.
La petición exacta a POST /process/ para el token te la comparte tu representante en Tonder
durante el onboarding, junto con la configuración de sandbox para este modelo. Esta página la
incluirá en cuanto se publique. Nada más cambia en tu integración de API Direct: mismo host, mismo
header Authorization, mismo X-Request-Id.
El token de pago de Apple
Lo que reenvías es el objeto paymentData que Apple devuelve — token.paymentData en la web,
PKPaymentToken.paymentData en una app iOS — exactamente como lo recibiste:
| Campo | Qué es |
|---|---|
version | El esquema de cifrado que usó Apple, EC_v1 para los certificados que Apple emite hoy |
data | Los datos de pago cifrados: el número de cuenta del dispositivo, su vencimiento y el criptograma |
signature | La firma de Apple sobre el token |
header.ephemeralPublicKey | La llave de un solo uso con la que Apple cifró data para tu certificado |
header.publicKeyHash | Un hash de la llave pública de tu certificado, que le dice a Tonder qué llave descifra este token |
header.transactionId | El identificador de Apple para esta autorización |
Reenvíalo completo y sin tocar: no recodifiques data, no omitas campos de header y no reutilices
un token — cada uno está ligado a una sola autorización. El formato es de Apple y está documentado
en la Payment token format reference.
La respuesta y el webhook son los de un pago de la API Direct, y GET /api/v1/transactions/{id}/
sigue siendo la fuente de verdad. Un rechazo del emisor llega como una transacción declinada, no
como un error de Apple Pay.
Lo que no cambia
- Webhooks. El cargo produce una transacción de la API Direct y el webhook que ya recibes. Ver Cómo funcionan los webhooks.
- Correlación. Envía
client_referenceymetadata.external_idcomo en cualquier pago; vuelven en el webhook. Ver Llaves de correlación. - Estado. Entrega con base en
GET /api/v1/transactions/{id}/o el webhook, nunca con la animación de éxito de la hoja.
Mantenlo funcionando: certificados y renovaciones
| Qué | Expira | Qué hacer |
|---|---|---|
| Merchant ID | Nunca | Nada |
| Payment Processing Certificate | Cada 25 meses | Apple avisa por correo al Account Holder y al Admin con anticipación. Antes de la fecha, pide a tu representante un CSR nuevo y repite el paso 2; Tonder reemplaza el certificado |
| Verificación del dominio (web) | Con el certificado SSL de tu dominio | Renueva el certificado SSL antes de que expire y Apple mantiene el dominio verificado; si caduca, vuelve a verificar el dominio en tu cuenta de Apple |
Apple publica estas reglas en Maintaining your environment.
Solución de problemas
Los códigos son los errores de Apple Pay que Tonder devuelve para este modelo.
| Qué ves | Por qué | Cómo se arregla |
|---|---|---|
EAP001 — el token no pudo descifrarse | El certificado de tu Merchant ID no se creó con el CSR de Tonder, o el token fue alterado, recodificado o reutilizado | Crea un certificado nuevo con el CSR de Tonder (paso 2); reenvía paymentData sin tocar |
EAP002 — no hay certificado configurado para tu negocio | El paso 3 no está completo en ese ambiente | Pide a tu representante que confirme que el ambiente está listo |
EAP003 — Apple rechazó la validación del comercio | El dominio no está verificado bajo tu Merchant ID, o Apple no puede llegar a él | Revisa el dominio en tu cuenta de Apple, los requisitos para servir el archivo y los rangos de IP de Apple |
EAP004 — monto o moneda no coinciden | El monto o la moneda que enviaste difieren de lo que el comprador autorizó en la hoja | Envía exactamente los valores que mostró la hoja; un carrito que cambió necesita una autorización nueva |
| Funciona en sandbox, falla en producción | Cada ambiente tiene su propio certificado y su propia habilitación | Repite los pasos 2 y 3 para producción |