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.
En esta página encontrarás todos los pasos para agregar, configurar y usar el Seamless SDK de iOS para realizar pagos en tu proyecto de iOS.
SDK recomendadoYuno recomienda usar el Seamless SDK de iOS para una integración fluida. Esta opción ofrece una solución de pago flexible con componentes de interfaz prediseñados y opciones de personalización.
Vista general del Seamless SDK de iOS

Paso 1: incluye la biblioteca en tu proyecto

Puedes agregar la biblioteca con CocoaPods o Swift Package Manager.

CocoaPods

Para agregar el Yuno SDK a tu proyecto de iOS, debes instalar el Yuno SDK. 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.
Después, debes ejecutar la instalación:

Swift Package Manager

Si usas Swift Package Manager, agrega el Yuno SDK como dependencia, como se muestra en el siguiente bloque de código:

Paso 2: inicializa el SDK con la clave pública

Para empezar a ejecutar el checkout Seamless de Yuno para iOS, primero debes obtener tu ID de app de Yuno y tu clave de API pública. Luego, importa e inicializa Yuno como se muestra en el siguiente fragmento de código:
UISceneDelegateSi tu app usa un UISceneDelegate, asegúrate de colocar el código de inicialización de Yuno dentro de tu SceneDelegate.
El checkout Seamless te permite configurar la apariencia del SDK. Es un paso opcional que configuras mediante la clase YunoConfig. Para definir las configuraciones, usa el siguiente bloque de código para configurar los elementos disponibles:
Configura el SDK con las siguientes opciones:
Acceso a tu clave de APIPuedes obtener tu clave de API en la sección Developers del Yuno Dashboard.

Crea una sesión de checkout

Antes de iniciar el proceso de pago, debes crear una checkout_session con el endpoint Crear sesión de checkout. Esta sesión inicializa el flujo de pago y se usará en el siguiente paso.
Controla la autorización frente a la captura enviando payment_method.detail.card.capture en la sesión de checkout: false = solo autorizar, true = capturar de inmediato.

Parámetros clave

Paso 3: inicia el checkout y el proceso de pago

El checkout seamless y el proceso de pago se inician con un único método, startPaymentSeamlessLite. En el ViewController, donde se mostrará Yuno, llama al método Yuno.startPaymentSeamlessLite(). Puedes usar el método con async/await o con callbacks:
Swift (async/await)
Swift (with callbacks)
La versión seamless requiere parámetros adicionales. Estos incluyen:
  • PaymentMethodSelected: el token almacenado y/o el método de pago que el cliente usará para realizar el pago.
  • SeamlessParams
Parámetros La siguiente tabla describe cada parámetro de SeamlessParams:
Requisitos de concurrencia de Swift 6Si usas Swift 6, deberás implementar el protocolo YunoPaymentDelegate con consideraciones específicas de concurrencia. Consulta la guía de Concurrencia en Swift 6 para conocer las opciones de implementación y las mejores prácticas.

Paso 4: gestiona el estado del pago (opcional)

Deep links y Mercado Pago Checkout ProEste paso solo es necesario si usas un método de pago que depende de deep links o de Mercado Pago Checkout Pro. Si tus métodos de pago no usan deep links, puedes omitir este paso.
Algunos métodos de pago sacan a los usuarios de tu app para completar la transacción. Una vez finalizado el pago, el usuario regresa a tu app mediante un deep link. El SDK usa este deep link para determinar qué ocurrió (si el pago fue exitoso, falló o se canceló) y puede mostrar una pantalla de estado al usuario. Para gestionarlo, debes actualizar tu AppDelegate para pasar la URL entrante de vuelta al Yuno SDK. Así, el SDK puede leer el resultado y, opcionalmente, mostrar el estado del pago. El siguiente fragmento de código muestra cómo agregarlo a tu app:
Este código escucha los deep links que abren tu app. Cuando se recibe una URL, verifica si el esquema coincide con el que usaste en el callback_url al configurar la sesión de checkout. Si coincide, la URL se pasa al Yuno SDK mediante Yuno.receiveDeeplink(_:), que lee el resultado del pago. Asegúrate de que el url.scheme de este código coincida con el callback_url que indicaste al crear la checkout_session.

Estado de la transacción

Una vez completado el pago, el SDK puede devolver distintos estados de la transacción. La lista de todos los estados posibles y sus descripciones se presenta en la siguiente tabla:

Validación del estado del pago

Esta sección explica cómo gestiona el SDK el estado del pago cuando los usuarios cancelan o abandonan los flujos de pago, y cómo se relaciona el estado del SDK con el estado del pago en el backend en estos escenarios.

Métodos de pago síncronos (Apple Pay)

En los métodos de pago síncronos como Apple Pay, cuando un usuario cancela o cierra la interfaz de la billetera antes de recibir la respuesta de un proveedor de servicios de pago (PSP):
  • Estado del SDK: devuelve userCancelled (CANCELLED_BY_USER)
  • Estado del pago en el backend: permanece en PENDING hasta que se agote el tiempo del PSP o el comercio cancele el pago
  • Importante: el SDK no devolverá reject ni processing en este escenario
Esto garantiza que el pago en el backend permanezca en estado pendiente y que el sistema del comercio pueda gestionarlo correctamente.

Métodos de pago asíncronos (PIX y métodos basados en QR)

En los métodos de pago asíncronos, cuando un usuario cierra la ventana de pago antes de completar el pago:
  • Estado del SDK: devuelve userCancelled*.
  • Estado del pago en el backend: permanece en PENDING y el código de pago sigue siendo válido hasta que expire.
  • Reutilización de la sesión de checkout: al reabrir la misma sesión de checkout se puede mostrar el mismo código de pago válido.
  • Sin cancelación automática: el pago no se cancela automáticamente en el backend cuando el usuario cierra la ventana.
  • Confirmación del estado: userCancelled significa que el comprador salió de la pantalla, y no implica que el pago haya fallado. Confirma el estado final mediante webhook o GET /v1/payments/{payment_id} antes de mostrar una cancelación.
* Los métodos de pago que muestran un código de pago o un comprobante (código QR de PIX, boleto, OXXO y similares), y Pix Parcelado, devuelven processing con el subestado CLOSED_BY_USER en lugar de userCancelled cuando el usuario cierra la pantalla. El pago permanece en PENDING en el backend y aún se puede completar.

Pagos asíncronos vencidos

Si un código QR de PIX vence de forma natural:
  • Estado en el backend: se actualiza a EXPIRED
  • Estado del SDK: los callbacks del SDK y los endpoints de sondeo devuelven EXPIRED de forma consistente
Esto garantiza que los comercios reciban información de estado precisa cuando un método de pago ha vencido. El estado de la transacción se puede gestionar de dos maneras al usar el método startPaymentSeamlessLite:
  • Async/Await: usa el enfoque async/await para un flujo más simplificado. Este método devuelve un Result de forma asíncrona, lo que hace que el código sea más fácil de leer y mantener.
  • Callback: puedes gestionar el estado de la transacción mediante una función callback, lo que permite una ejecución inmediata en cuanto el resultado está disponible.
Ambas opciones ofrecen flexibilidad según tu enfoque preferido para el código asíncrono.
Evalúa result.status con switch, no result directamente.

Funciones complementarias

El Yuno SDK de iOS ofrece servicios y configuraciones adicionales que puedes usar para mejorar la experiencia de los clientes. Usa las personalizaciones del SDK para cambiar la apariencia del SDK y adaptarla a tu marca o para configurar el loader.
  • Loader: controla el uso del loader mediante las opciones de configuración del SDK.
  • Guardar tarjeta para pagos futuros: además, puedes mostrar una casilla para guardar o inscribir tarjetas con saveCardEnabled: true. A continuación encontrarás ejemplos de la casilla en ambos formatos del formulario de tarjeta.
Guardar tarjeta para pagos futuros

Gestión de errores

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