Saltar al contenido principal
Esta guía describe cómo integrar Apple Pay directamente con la API de Yuno. La integración directa ofrece control total sobre el flujo de pago y es ideal para comercios que necesitan implementaciones personalizadas o que ya cuentan con sistemas de pago. La integración directa de Apple Pay de Yuno admite pagos únicos y recurrentes (útiles para suscripciones y otras transacciones periódicas).
Antes de implementar pagos con Apple Pay, asegúrate de haber completado los requisitos previos de Apple Pay.

Descripción general de Apple Pay

  1. El cliente inicia el pago en su dispositivo iOS
  2. Recibe el payment_token mediante el SDK de Apple
  3. Crea un pago con Yuno incluyendo el token convertido en cadena de texto
  4. Yuno lo procesa con tu proveedor o proveedores configurados y devuelve una respuesta
  5. Supervisa el estado de la respuesta mediante webhooks

Campos de la solicitud

La solicitud de crear un pago para Apple Pay usa los campos siguientes. El requisito se muestra por flujo: pago único, CIT (el primer pago de una serie recurrente) y MIT (los pagos recurrentes posteriores).
  • payment_token es la respuesta completa del SDK de Apple Pay enviada como una cadena JSON (convertida en cadena de texto).
  • Si no envías workflow: "DIRECT", la API exige un checkout.session en su lugar.
  • vault_on_success necesita customer_payer.id. customer_payer.id debe hacer referencia a un cliente existente (créalo primero con Create Customer). Sin él, el pago igualmente es exitoso, pero no se almacena nada: la respuesta incluye un vaulted_token vacío y ningún error.
  • Envía el encabezado X-Idempotency-Key en cada llamada para crear un pago, para evitar cargos duplicados.
  • Los campos obligatorios para Apple Pay son los mismos para todos los proveedores. Ningún proveedor requiere campos adicionales de datos del cliente para Apple Pay.

Pagos únicos

Para integrar una sola transacción, como una compra en línea, usa la API de Yuno para crear un pago. Esto requiere que obtengas cierta información de la respuesta del SDK de Apple, que se genera cuando el cliente autoriza el pago.

Ejemplo de respuesta de Apple Pay

El SDK de Apple Pay devuelve un objeto como el del ejemplo siguiente, a esta respuesta la llamamos payment_token.

Ejemplo de solicitud de pago único

A continuación se muestra un ejemplo de una solicitud de pago único con Apple Pay usando la API directa de Yuno. La solicitud incluye la respuesta de Apple Pay convertida en cadena de texto dentro de payment_token, tal como se recibe del SDK de Apple Pay, junto con campos obligatorios como el monto, la moneda y la información de la cuenta. Ajusta los valores según sea necesario para tu integración.

Pagos recurrentes con la API directa

Los pagos recurrentes con Apple Pay mediante la integración directa requieren implementar transacciones iniciadas por el cliente (CIT) y transacciones iniciadas por el comercio (MIT).
  • Transacción iniciada por el cliente (CIT): la primera transacción, en la que el cliente autoriza los pagos recurrentes. Esta genera un vaulted_token para uso futuro.
  • Transacción iniciada por el comercio (MIT): transacciones automáticas posteriores que usan el vaulted_token sin interacción del cliente.

Transacción iniciada por el cliente (CIT)

Cuando un cliente autoriza la suscripción y tienes una respuesta del SDK de Apple, usa el payment_token convertido en cadena de texto en la API para crear un pago de Yuno para crear la CIT.

Parámetros clave para CIT

  • vault_on_success: true: indica que esta es la configuración de un pago recurrente y genera el token almacenado para futuras transacciones MIT
  • detail.wallet.stored_credentials.usage: FIRST: indica que esta es la transacción inicial de una serie recurrente
  • detail.wallet.payment_token: debe ser la respuesta del SDK de Apple convertida en cadena de texto, el payment_token

Manejo de la respuesta de la CIT

Cuando la CIT es exitosa, recibirás una respuesta que contiene el vaulted_token. Puede usarse para transacciones posteriores. Almacénalo cifrado en reposo y restringe el acceso solo a los sistemas que lo necesiten para crear cobros MIT.
La respuesta del pago es el único lugar donde se devuelve el vaulted_token. Los instrumentos de billetera almacenados intencionalmente no se incluyen en Retrieve Enrolled Payment Methods, por lo que no dependas de la lista de métodos de pago del cliente para volver a obtener el token: consérvalo (junto con cualquier metadato de visualización que necesites) cuando la CIT sea exitosa. Un token almacenado aún puede resolverse individualmente con Retrieve Enrolled Payment Method by ID. Consulta Stored Credentials para conocer las reglas de etiquetado de los tokens de billetera almacenados.

Transacción iniciada por el comercio (MIT)

Las transacciones MIT se procesan automáticamente para la facturación recurrente usando el vaulted_token de la CIT.

Ejemplo de solicitud MIT

Parámetros clave para MIT

  • vaulted_token: el token almacenado generado durante la CIT
  • detail.card.stored_credentials.usage: "USED": indica que esta es una transacción posterior de una serie recurrente
  • No se requiere payment_token: usa en su lugar el vaulted_token almacenado

Solución de problemas

  • Falló la validación del comercio: verifica los certificados de Apple Pay y la configuración del ID de comercio
  • Token de Apple no válido o vencido: obtén un token nuevo del SDK de Apple y asegúrate de que esté convertido en cadena de texto
  • Red o país no compatible: confirma que tu proveedor admite Apple Pay para la moneda y el país solicitados
  • Cargos duplicados: envía siempre un Idempotency-Key en las llamadas para crear un pago