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.
- Quieren controlar el flujo de pago y aprovechar componentes de interfaz de usuario predefinidos
- Necesitan personalizar la experiencia de pago sin dejar de cumplir con PCI
- Requieren un equilibrio entre la velocidad de implementación y la personalización
- Componentes de interfaz de usuario de pago predefinidos con opciones de personalización
- Compatibilidad con varios métodos de pago
- Manejo avanzado del estado del pago
- Gestión integral de errores
Requisitos
Antes de iniciar la integración del Yuno Android SDK, asegúrate de que tu proyecto cumpla los requisitos técnicos. Asegúrate también de contar con los siguientes requisitos previos:- Versión mínima del SDK:
minSdkVersion23 o superior (Android 6.0). Es obligatoria desde el Yuno Android SDK 2.24.0 - Java: Java 8 habilitado
- AndroidX: usa AndroidX en lugar de las bibliotecas de soporte anteriores
- Android Gradle Plugin: 4.0.0 o superior
- Kotlin Gradle Plugin: 1.4.0 o superior
- ProGuard: 6.2.2 o superior
Configuración de ProGuard / R8
Si tu proyecto tieneminifyEnabled = true, agrega estas reglas a tu archivo proguard-rules.pro para que el SDK funcione correctamente, especialmente con el modo completo de R8 en AGP 8.x o superior.
Reglas oficiales de ProGuard / R8 de Yuno
Reglas oficiales de ProGuard / R8 de Yuno
¿Por qué son necesarias estas reglas?
AGP 8.x o superior habilita por defecto el modo completo de R8, que elimina de forma agresiva las firmas de tipos genéricos. Sin-keepattributes Signature, TypeToken<T> de Gson puede fallar en tiempo de ejecución con java.lang.Class cannot be cast to java.lang.reflect.ParameterizedType.Verifica la versión del SDKConsulta las notas de la versión o el repositorio del Yuno Android SDK para verificar cuál es la versión actual del SDK disponible.
Paso 1: Crear un cliente
Crea un cliente con el endpoint Create customer antes de iniciar pagos. Este paso es obligatorio para:- Identificar a la persona que realiza el pago
- Habilitar la función de tarjetas guardadas (si está habilitada)
- Hacer seguimiento del historial de pagos
checkout_session.
Paso 2: Crear una sesión de checkout
Crea una nuevacheckout_session con el endpoint Create checkout session para inicializar el flujo de pago. Asegúrate de:
- Incluir el ID del cliente que obtuviste en el paso anterior
- Guardar el ID de la
checkout_sessiondevuelta para usarlo en el Paso 6 de la integración
Controla la autorización o 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: Agregar el SDK a tu proyecto
Agrega la fuente del repositorio:build.gradle para agregar la dependencia del Yuno SDK a la aplicación:
Paso 4: Configurar los permisos
El Yuno SDK requiere permisos de red. Asegúrate de que el permisoINTERNET esté incluido en tu AndroidManifest.xml:
Paso 5: Inicializar el SDK
Obtén tus claves públicas de API en el Dashboard de Yuno. Si aún no has implementado una aplicación personalizada, crea una. En el métodoonCreate() de la clase de tu aplicación, llama a la función de inicialización (Yuno.initialize):
YunoConfig para definir configuraciones adicionales del SDK. La siguiente tabla enumera y describe las opciones de personalización:
El siguiente bloque de código muestra un ejemplo de
YunoConfig:
Paso 6: Iniciar el checkout
Llama al métodostartCheckout en la función onCreate() de la actividad que integra el SDK para iniciar un nuevo proceso de pago con el Seamless SDK:
Los posibles estados de pago que devuelve
callbackPaymentState son:
Validación del estado del pago
Esta sección explica cómo maneja 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 (Google Pay)
En los métodos de pago síncronos, como Google Pay, cuando un usuario cancela o cierra la interfaz de la billetera antes de recibir la respuesta del proveedor de servicios de pago (PSP):- Estado del SDK: devuelve
CANCELED_BY_USER - Estado del pago en el backend: permanece
PENDINGhasta que se agote el tiempo de espera del PSP o el comercio cancele el pago - Importante: en este escenario el SDK no devolverá
REJECTniPROCESSING
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
CANCELED_BY_USER*. - Estado del pago en el backend: permanece
PENDINGy el código de pago sigue siendo válido hasta que expire. - Reutilización de la sesión de checkout: al volver a abrir la misma sesión de checkout, puede mostrarse 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:
CANCELED_BY_USERsignifica que el comprador salió de la pantalla, no que el pago haya fallado. Confirma el estado final mediante un 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 CANCELED_BY_USER cuando el usuario cierra la pantalla. El pago permanece PENDING en el backend y todavía 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 consulta (polling) devuelven
EXPIREDde forma consistente
Paso 7: Obtener el token de un solo uso (OTT) del pago
Llama al métodostartPaymentSeamlessLite para iniciar un proceso de pago:
Recibirás el estado del pago mediante
callbackPaymentState, que indicará si el pago fue exitoso o si ocurrió algún problema.
Paso 8: Crear el pago
Llama al métodostartPaymentSeamlessLite con el método de pago seleccionado para completar el proceso de pago:
Funciones complementarias
El Yuno Android SDK ofrece servicios y configuraciones adicionales que puedes usar para mejorar la experiencia de tus clientes. Usa la personalización del SDK para cambiar la apariencia del SDK y adaptarla a tu marca, o para configurar el loader.styles
Con la opción de personalización styles, puedes definir estilos visuales globales mediante un objeto YunoStyles. Te permite aplicar una marca coherente en todo el SDK personalizando la apariencia de los botones y la tipografía.
El objeto
YunoButtonStyles te permite definir configuraciones específicas para la apariencia de los botones:
YunoConfig, descrita en el Paso 5, para usar la opción de personalización styles.
Loader
La funcionalidad del loader se controla mediante el parámetrokeepLoader de la clase de datos YunoConfig, que se documenta en línea en la sección anterior de configuración del SDK.
Autocompletar de Google
Desde la versión 2.16.0 del Android SDK, los campos del número de tarjeta, el nombre del titular de la tarjeta, la fecha de vencimiento y el CVV son elegibles para el autocompletar de Google. Cuando el cliente se posiciona en cualquiera de estos campos, la interfaz de autocompletar de Android puede sugerir una tarjeta guardada en su cuenta de Google, y al seleccionarla se completa el formulario automáticamente.Esto aplica a cualquier usuario de Android que pague con tarjeta. No está vinculado al método de pago Google Pay. No se necesita ningún feature flag ni configuración adicional; se activa automáticamente una vez que actualizas a la versión 2.16.0 o posterior.
Guardar tarjeta para pagos futuros
También puedes mostrar una casilla para guardar o inscribir tarjetas concardSaveEnable: true. Los siguientes ejemplos muestran la casilla en ambos formatos del formulario de tarjeta:
Acceso a la app de demostraciónAdemás de los ejemplos de código incluidos, puedes consultar el repositorio de Yuno para completar la implementación de los Yuno Android SDK.