Saltar al contenido principal
Esta página documenta un SDK heredado. ¿Vas a iniciar una nueva integración? Usa el Yuno SDK. ¿Ya usas un SDK heredado? Sigue la guía de migración.El nuevo Yuno SDK (Web v2.x, iOS v3.x, Android v3.x, React Native v2.x) reemplaza los SDK Full, Lite, Seamless, Render, Headless y Secure Fields con una sola API en todas las plataformas. Los SDK heredados siguen siendo compatibles en paralelo durante la transición y está previsto dejarlos de usar en 2027. Contacta a tu Account Manager para planificar la migración.
Orientación: elige tu flujo de integración. Antes de comenzar, revisa el flujo de integración oficial.
  • Flujo estándar (Full Checkout): Recomendado para la mayoría de los comercios. Yuno se encarga de la interfaz, la seguridad y las actualizaciones automáticas de los métodos de pago.
  • Flujo personalizado (este SDK): Úsalo solo si necesitas control total sobre la experiencia de usuario. Nota: Serás responsable de gestionar manualmente los estados de los pagos, las transiciones de 3DS y la recopilación de datos para el enrutamiento de fraude.
El Headless SDK de Yuno para iOS te permite crear pagos e inscribir métodos de pago de forma simultánea. Al usar el Headless SDK, ten en cuenta que debes solicitar y enviar por API todos los campos obligatorios que exige el proveedor de pago. Estos campos son necesarios para generar el pago en la API del proveedor. El Headless SDK de Yuno te permite crear pagos en dos escenarios diferentes:
  • Crear un token de un solo uso con la información de una tarjeta de crédito o de métodos de pago alternativos y luego crear un pago.
  • Crear un token de un solo uso con un vaulted_token de un método de pago inscrito previamente. Esto recopila la información relevante para los proveedores de fraude antes de que crees un pago.
Los siguientes pasos describen cómo crear un pago con el Headless SDK de Yuno.

Paso 1: Incluye la biblioteca en tu proyecto

El primer paso es instalar el Yuno SDK en tu proyecto de iOS.
Verifica las versiones del iOS SDKPara ver todas las versiones disponibles, visita la página de versiones en el repositorio del iOS SDK de Yuno.
Puedes instalar el Yuno SDK de dos maneras:
  • Cocoapods: Si no tienes un Podfile, sigue la guía de CocoaPods para crear uno. Después de crear el Podfile, integrarás el Yuno SDK con Cocoapods agregando la siguiente línea a tu Podfile:
  • Swift Package Manager: Configura el paquete de Swift y luego agrega el Yuno SDK como dependencia, como se muestra en el siguiente bloque de código:

Paso 2: Inicializa el Headless SDK con la clave pública

Para inicializar el Headless SDK, debes importar Yuno y proporcionar una PUBLIC_API_KEY válida. Si no tienes tus credenciales de API, accede a la página Developers (Credentials) para ver cómo obtenerlas desde el dashboard.
Inicialización con UISceneDelegateSi tu aplicación usa un UISceneDelegate, asegúrate de colocar el código de inicialización de Yuno dentro de tu SceneDelegate.
El siguiente bloque de código presenta un ejemplo de cómo importar e inicializar Yuno.
Requisitos de concurrencia de Swift 6Si usas Swift 6, necesitarás manejar la concurrencia correctamente al usar los métodos asíncronos del SDK. Consulta la guía Concurrencia en Swift 6 para ver opciones de implementación detalladas y mejores prácticas.

Paso 3: Inicia el proceso de checkout

A continuación, iniciarás el proceso de checkout con la función apiClientPayment, proporcionando los parámetros de configuración necesarios. Debes llamar a esta función cuando tu cliente seleccione el método de pago. Como resultado, el SDK comenzará a recopilar la información relevante para 3DS y para las herramientas de prevención de fraude que hayas configurado en tu enrutamiento.

Parámetros

La siguiente tabla enumera todos los parámetros obligatorios y sus descripciones. El siguiente bloque de código presenta un ejemplo de la configuración de los parámetros.

Paso 4: Genera el token

Después de recopilar toda la información del usuario, puedes iniciar el pago. Primero, debes crear un token de un solo uso (OTT) con la función apiClientPayment.generateToken. Como es una función asíncrona, puedes usar do/catch para asegurarte de manejar correctamente los errores que se produzcan. A continuación, encontrarás dos ejemplos de escenarios diferentes para crear un token de un solo uso:
  1. Ejemplo 1: Crea un token de un solo uso con una tarjeta como método de pago e incluyendo toda la información requerida de la tarjeta.
  2. Ejemplo 2: Crea un token de un solo uso con la información del vaulted_token.
Ventajas de usar un token almacenado (vaulted token)Usar un vaulted token con el SDK garantiza que toda la información de fraude de los proveedores que configuraste se recopile y se adjunte al token de un solo uso. Además, puedes incluir detalles de cuotas y un código de seguridad si el proveedor lo requiere.
Example 1
Example 2
El siguiente bloque de código presenta las respuestas de la función apiClientPayment.generateToken para ambos ejemplos anteriores. La respuesta es un diccionario de tipo [String: Any].
Example 1
Example 2

Paso 5: Crea el pago

Una vez que hayas completado los pasos descritos anteriormente, puedes crear el pago. Llama al endpoint Crear pago desde tu backend justo después de generar el token, usando el token de un solo uso y la sesión de checkout. La respuesta del endpoint incluye el parámetro sdk_action_required, que indica si se necesitan acciones adicionales para completar el pago: En los métodos de pago síncronos, el pago se completa al instante. En este caso, sdk_action_required será false en la respuesta de la API y el proceso de pago termina. Si el pago requiere más interacción del SDK para completar el flujo, sdk_action_required será true. En ese caso, continúa con el Paso 6 para ver las instrucciones.

Paso 6: Procesa pagos asíncronos (opcional)

Un pago con 3DS puede requerir un desafío adicional para verificar la identidad del cliente, como se describe en la página Verificación de tarjetas con 3DS. Si es necesario un desafío de verificación 3DS, la respuesta del endpoint Crear pago contendrá:
  • Estado igual a PENDING y subestado igual a WAITING_ADDITIONAL_STEP
  • sdk_action_required = true
Para realizar el desafío y finalizar el pago, usa la siguiente opción de integración:

Completa el desafío 3DS

Para completar el desafío 3DS de un pago con tarjeta que creaste desde tu servidor, llama a la función continueCardPayment en tu cliente Headless. El SDK recuperará el estado del pago, presentará el desafío 3DS a tu cliente y te informará de cada actualización del estado del pago.
continueCardPayment solo admite pagos con CARD.
La función está disponible en la misma instancia de YunoPaymentHeadless que usaste para generar el token de un solo uso. A continuación, se muestra un ejemplo completo:
Cuando llamas a continueCardPayment, el SDK hará lo siguiente:
  1. Recuperar el estado actual del pago asociado con el checkoutSession.
  2. Presentar el desafío 3DS en una vista web segura, sobre la pantalla actual de tu aplicación.
  3. Cerrar el desafío automáticamente una vez que el cliente lo complete.
  4. Escuchar el resultado de la transacción en tiempo real y entregar cada actualización de estado mediante el closure onResult, que se invoca en el hilo principal.
El closure onResult puede llamarse más de una vez. Recibirás el estado intermedio processing mientras se confirma la transacción, seguido de un estado final (succeeded, reject, fail, userCancelled o internalError).
Obsoleto: getThreeDSecureChallengeEl método getThreeDSecureChallenge quedó obsoleto en la versión 2.18.0. Usa continueCardPayment en su lugar.

Manejo de errores

Maneja en tu aplicación los errores que devuelve el SDK, como pagos fallidos o errores de validación. Para ver los códigos de estado HTTP y de respuesta, consulta Códigos de estado y de respuesta en la referencia de la API.