Apple Pay

Apple Pay permite cobrar con las tarjetas que el comprador tiene guardadas en Wallet, desde un iPhone, iPad o Mac. Hay dos maneras de aceptarlo:

Checkout de ONVO: activá Apple Pay en el Dashboard y el botón aparece en tu Checkout, sin código.
Tu propio sitio: registrá tu dominio, mostrá el botón con ONVO.js y cobrá con intenciones de pago.

Apple Pay acepta tarjetas Visa, Mastercard y American Express, para cuentas de Costa Rica, en CRC y USD.

Referencia API relacionada

Paso	Referencia	Payloads
Registrar un dominio	POST /v1/payment-method-domains	Solicitud · Respuesta
Listar dominios	GET /v1/payment-method-domains	Parámetros · Respuesta
Obtener un dominio	GET /v1/payment-method-domains/{id}	Respuesta
Habilitar o deshabilitar un dominio	POST /v1/payment-method-domains/{id}	Solicitud · Respuesta
Validar un dominio de nuevo	POST /v1/payment-method-domains/{id}/validate	Respuesta
Consultar disponibilidad	GET /v1/apple-pay/availability	Parámetros · Respuesta
Crear la intención	POST /v1/payment-intents	Solicitud · Respuesta
Confirmar la intención	POST /v1/payment-intents/{id}/confirm	Solicitud · Respuesta

Antes de empezar

Activá Apple Pay en el Dashboard, en Configuración → Métodos de pago. Requiere pagos con tarjeta activos, y el interruptor aplica por modo: prueba y producción se activan por separado.
Tu cuenta debe estar activada. ONVO registra el comercio ante Apple solo después de la activación, también en modo de prueba.
Al activar Apple Pay o registrar un dominio aceptás los términos de Apple Pay para comercios web.
El botón solo aparece en dispositivos Apple con una tarjeta en Wallet. Funciona tanto en Safari como en Chrome; lo que decide es el dispositivo y la tarjeta, no el navegador.

Checkout de ONVO (sin código)

Si cobrás con Checkout, basta con activar Apple Pay en el Dashboard. ONVO registra automáticamente el comercio ante Apple —toma unos segundos y el estado queda visible en la misma pantalla— y el botón aparece en tu Checkout para los dispositivos Apple compatibles. No necesitás nada más de esta guía.

Apple Pay en tu propio sitio

Cuatro pasos: publicá el archivo de asociación de dominio, registrá el dominio, mostrá el botón con ONVO.js y cobrá desde tu servidor con una intención de pago.

1. Publicá el archivo de asociación

Descargá el archivo de asociación de dominio de ONVO:

https://checkout.onvopay.com/.well-known/apple-developer-merchantid-domain-association

Es el mismo archivo para todos los comercios de ONVO. Servilo sin modificar en cada dominio donde vas a mostrar el botón, en la misma ruta y sin extensión:

https://tienda.ejemplo.com/.well-known/apple-developer-merchantid-domain-association

La URL debe responder 200 directamente, sin redirecciones, desde una dirección HTTPS pública.
Cada subdominio que muestra el botón se registra por separado: ejemplo.com, www.ejemplo.com y tienda.ejemplo.com son tres dominios.

2. Registrá el dominio

Desde tu servidor, con tu llave secreta:

curl https://api.onvopay.com/v1/payment-method-domains \
  -X POST \
  -H "Authorization: Bearer $ONVO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domainName": "tienda.ejemplo.com"
  }'

ONVO verifica el archivo en el momento —típicamente uno o dos segundos— y registra el dominio para Apple Pay:

{
  "id": "cm1pmd8k2x0001a8f3h2k9q7z",
  "domainName": "tienda.ejemplo.com",
  "enabled": true,
  "mode": "live",
  "applePay": { "status": "active" },
  "createdAt": "2026-09-27T18:04:11.201Z",
  "updatedAt": "2026-09-27T18:04:11.201Z"
}

Si el archivo falta o es distinto, el dominio se crea igual pero queda inactive, y applePay.statusDetails.errorMessage explica el motivo. Corregí el archivo y reintentá con POST /v1/payment-method-domains/{id}/validate; permite un intento por dominio por minuto.

Para administrar tus dominios:

GET /v1/payment-method-domains lista los dominios con su estado.
GET /v1/payment-method-domains/{id} retorna un dominio.
POST /v1/payment-method-domains/{id} con { "enabled": false } oculta Apple Pay en el dominio sin borrar el registro; con { "enabled": true } lo muestra de nuevo de inmediato.

Un dominio registrado con una llave de producción también funciona en modo de prueba. Registrar un dominio que ya existe retorna el dominio existente.

3. Mostrá el botón con ONVO.js

En el navegador, con tu llave pública, incluí el SDK de Apple Pay de Apple y ONVO.js:

<script src="https://applepay.cdn-apple.com/jsapi/1.latest/apple-pay-sdk.js"></script>
<script src="https://js.onvopay.com/v1/"></script>

<apple-pay-button id="apple-pay" buttonstyle="black" type="buy" locale="es-CR" style="display: none"></apple-pay-button>

<script>
  const onvo = ONVO("onvo_live_publishable_key_...");

  const applePay = onvo.applePay({
    countryCode: "CR",
    currencyCode: "CRC",
    total: { label: "Mi tienda", amount: "5000.00" },
  });

  const button = document.getElementById("apple-pay");

  applePay.isAvailable().then((available) => {
    if (available) button.style.display = "inline-block";
  });

  button.addEventListener("click", () => {
    // begin() debe llamarse de forma sincrónica dentro del click: Apple Pay lo exige.
    applePay.begin({
      async onPaymentMethod({ paymentMethodId, complete }) {
        const response = await fetch("/checkout/pay", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({ paymentMethodId }),
        });
        const intent = await response.json();
        complete(intent.status === "succeeded" ? "success" : "failure");
      },
      onCancel: () => {},
      onError: (error) => console.error(error),
    });
  });
</script>

isAvailable() responde true solo cuando el dispositivo es compatible y el dominio está activo para tu cuenta. Si devuelve false en un dispositivo compatible, consultá GET /v1/apple-pay/availability con tu llave pública para ver el motivo (not_enabled, domain_not_registered, domain_inactive o domain_disabled).
ONVO.js maneja la validación del comercio ante Apple y crea el método de pago; tu callback onPaymentMethod recibe el paymentMethodId listo para confirmar.
El SDK de Apple no es opcional. Además del botón, define window.ApplePaySession, que es la API que ONVO.js usa para abrir la hoja de pago. Safari la trae nativa, pero los demás navegadores no: sin ese script, en Chrome isAvailable() responde false y el botón nunca aparece.

4. Cobrá desde tu servidor

Creá la intención de pago con tu llave secreta. El monto va en la unidad mínima de la moneda: 500000 representa ₡5,000.00 y debe coincidir con el total de la hoja de pago (total.amount: "5000.00" en el ejemplo anterior).

curl https://api.onvopay.com/v1/payment-intents \
  -X POST \
  -H "Authorization: Bearer $ONVO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500000,
    "currency": "CRC",
    "description": "Orden #1001"
  }'

Confirmá la intención con el paymentMethodId que recibió tu endpoint:

curl https://api.onvopay.com/v1/payment-intents/$PAYMENT_INTENT_ID/confirm \
  -X POST \
  -H "Authorization: Bearer $ONVO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentMethodId": "cl502zv0d0127ebdp3zt27651"
  }'

Si status es succeeded, el pago está aprobado: llamá complete('success') para cerrar la hoja de Apple Pay. Si la confirmación falla, la intención vuelve a requires_payment_method con el detalle en lastPaymentError: llamá complete('failure') y, si el comprador quiere reintentar, abrí una hoja nueva.

Identificá un pago con Apple Pay

La intención de pago indica que el cobro vino de Apple Pay en paymentMethod.card.wallet. Sirve para tus recibos, tu conciliación o tu panel interno:

{
  "paymentMethod": {
    "type": "card",
    "card": {
      "brand": "Visa",
      "last4": "3599",
      "wallet": { "type": "apple_pay" }
    }
  }
}

El last4 es el de la tarjeta del dispositivo, no el de la tarjeta física del comprador: Apple entrega un número de cuenta de dispositivo distinto por cada dispositivo. La marca (brand) sí es la real. Cuando el pago no vino de un wallet, wallet es null.

Importante

Credencial de un solo uso

La credencial de Apple Pay sirve para un solo cobro y expira pocos minutos después de la aprobación del comprador. Confirmá la intención de inmediato y no guardés el paymentMethodId para después. Si la confirmación falla, un reintento requiere abrir una hoja de pago nueva. Apple Pay no está soportado para cobros recurrentes por ahora.

Errores comunes y su causa:

Código	Causa
`apple_pay.not_enabled`	Apple Pay no está activado en el Dashboard para la cuenta en ese modo.
`apple_pay.account_not_activated`	La cuenta todavía no está activada.
`apple_pay.domain_not_verified`	La página que abre Apple Pay no está en un dominio activo y habilitado de la cuenta.
`apple_pay.domain_validate_cooldown`	Esperá un minuto antes de validar el mismo dominio de nuevo.
`apple_pay.token_replayed`	Esa credencial de Apple Pay ya se usó; abrí una hoja nueva.
`apple_pay.merchant_session_failed`	Apple no aceptó la sesión del comercio. Reintentá; si persiste, contactá a soporte.
`apple_pay_unsupported_network`	La tarjeta es de una red que ONVO no acepta por Apple Pay. Las aceptadas son Visa, Mastercard y American Express.

Dominios Apple Pay en el Dashboard

También podés administrar los dominios sin código desde el Dashboard. Entrá a Configuración → Métodos de pago y, en la fila de Apple Pay, seleccioná Administrar dominios para abrir la pantalla Dominios de Apple Pay. Desde ahí podés ver tus dominios con su estado, descargar el archivo de asociación, registrar un dominio nuevo, reintentar la validación y deshabilitar un dominio. La pantalla está disponible cuando Apple Pay está habilitado para tu cuenta.

Pruebas

En modo de prueba, con llaves onvo_test_, los cargos se simulan y no se mueve dinero, pero la hoja de pago, el registro de dominios y el flujo completo son reales. Probá con un dispositivo Apple real y cualquier tarjeta guardada en Wallet: las tarjetas sandbox de Apple no aplican en la plataforma de ONVO.

Para desarrollo local, el dominio debe servirse por HTTPS desde una dirección pública —por ejemplo, un túnel— y registrarse igual que en producción. localhost no es registrable.

Referencia API relacionada​

Antes de empezar​

Checkout de ONVO (sin código)​

Apple Pay en tu propio sitio​

1. Publicá el archivo de asociación​

2. Registrá el dominio​

3. Mostrá el botón con ONVO.js​

4. Cobrá desde tu servidor​

Identificá un pago con Apple Pay​

Importante​

Dominios Apple Pay en el Dashboard​

Pruebas​