Antes de implementar pagos con Apple Pay, asegúrate de haber completado los requisitos previos de Apple Pay.
Descripción general de Apple Pay
- El cliente inicia el pago en su dispositivo iOS
- Recibe el
payment_tokenmediante el SDK de Apple - Crea un pago con Yuno incluyendo el token convertido en cadena de texto
- Yuno lo procesa con tu proveedor o proveedores configurados y devuelve una respuesta
- 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_tokenes 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 uncheckout.sessionen su lugar. vault_on_successnecesitacustomer_payer.id.customer_payer.iddebe 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 unvaulted_tokenvacío y ningún error.- Envía el encabezado
X-Idempotency-Keyen 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 llamamospayment_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 depayment_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_tokenpara uso futuro. -
Transacción iniciada por el comercio (MIT): transacciones automáticas posteriores que usan el
vaulted_tokensin 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 elpayment_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 MITdetail.wallet.stored_credentials.usage: FIRST: indica que esta es la transacción inicial de una serie recurrentedetail.wallet.payment_token: debe ser la respuesta del SDK de Apple convertida en cadena de texto, elpayment_token
Manejo de la respuesta de la CIT
Cuando la CIT es exitosa, recibirás una respuesta que contiene elvaulted_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 elvaulted_token de la CIT.
Ejemplo de solicitud MIT
Parámetros clave para MIT
vaulted_token: el token almacenado generado durante la CITdetail.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 elvaulted_tokenalmacenado
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-Keyen las llamadas para crear un pago