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.
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.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:YunoConfig. Para definir las configuraciones, usa el siguiente bloque de código para configurar los elementos disponibles:
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 unacheckout_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)
PaymentMethodSelected: el token almacenado y/o el método de pago que el cliente usará para realizar el pago.
SeamlessParams
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.
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:
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
PENDINGhasta que se agote el tiempo del PSP o el comercio cancele el pago - Importante: el SDK no devolverá
rejectniprocessingen este escenario
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
PENDINGy 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:
userCancelledsignifica que el comprador salió de la pantalla, y no implica que el pago haya fallado. Confirma el estado final mediante webhook oGET /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
EXPIREDde forma consistente
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.
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.