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.
Esta página es una guía del Seamless SDK de Yuno para pagos en Android.
SDK recomendadoYuno recomienda usar el Android Seamless SDK para una integración fluida. Esta opción ofrece una solución de pago flexible con componentes de interfaz de usuario predefinidos y opciones de personalización.
Este SDK es ideal para comercios que:
  • 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
El Seamless SDK incluye funciones como:
  • 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
Si necesitas un control total de la interfaz de usuario o funciones más avanzadas, considera usar el Full SDK de Yuno. Descripción general del Seamless SDK para Android

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: minSdkVersion 23 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 tiene minifyEnabled = 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.

¿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
El ID del cliente que devuelve este endpoint se usará al crear la checkout_session.

Paso 2: Crear una sesión de checkout

Crea una nueva checkout_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_session devuelta 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

Uso de la sesión de checkoutLa checkout_session es única para cada intento de pago y no se puede reutilizar.

Paso 3: Agregar el SDK a tu proyecto

Agrega la fuente del repositorio:
Incluye el siguiente código en el archivo 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 permiso INTERNET 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étodo onCreate() de la clase de tu aplicación, llama a la función de inicialización (Yuno.initialize):
Usa la clase de datos 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étodo startCheckout 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:
La siguiente tabla ofrece información adicional sobre los posibles estados:

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 PENDING hasta que se agote el tiempo de espera del PSP o el comercio cancele el pago
  • Importante: en este escenario el SDK no devolverá REJECT ni PROCESSING
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 CANCELED_BY_USER*.
  • Estado del pago en el backend: permanece PENDING y 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_USER significa que el comprador salió de la pantalla, no que el pago haya fallado. Confirma el estado final mediante un 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 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 EXPIRED de forma consistente
Esto garantiza que los comercios reciban información precisa sobre el estado cuando un método de pago ha vencido.

Paso 7: Obtener el token de un solo uso (OTT) del pago

Llama al método startPaymentSeamlessLite para iniciar un proceso de pago:
La siguiente tabla describe los parámetros para iniciar el 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étodo startPaymentSeamlessLite 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:
Usa la clase de datos 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ámetro keepLoader 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 con cardSaveEnable: true. Los siguientes ejemplos muestran la casilla en ambos formatos del formulario de tarjeta: Guardar tarjeta para pagos futuros
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.

Manejo de errores

Gestiona en tu aplicación los errores que devuelve el SDK, incluidos los pagos fallidos y los errores de validación. Para consultar los códigos de estado HTTP y de respuesta, consulta Estado y códigos de respuesta en la referencia de la API.