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.
Esta página es una guía del Yuno Headless Android SDK para pagos. Este SDK es ideal para comercios que:
  • Necesitan control total sobre la interfaz de pago y la experiencia del usuario
  • Quieren crear flujos de pago personalizados
  • Requieren capacidades de integración avanzadas
El Headless SDK incluye funciones principales como:
  • Acceso directo a la API para el procesamiento de pagos
  • Generación de tokens para métodos de pago
  • Gestión de la autenticación 3DS
  • Recopilación de datos para la prevención de fraude
Si prefieres una solución con interfaz prediseñada, considera usar el Full Checkout SDK o el Lite SDK de Yuno.

Requisitos

Antes de comenzar 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 prerrequisitos:
  • Minimum SDK Version: minSdkVersion 23 o superior (Android 6.0). Requerido desde 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
  • ProGuard: 6.2.2 o superior
  • Kotlin Gradle Plugin: 1.4.0 o superior
  • ELF Page Size Support: cumple los requisitos de alineación de página ELF de 16 KB de Google (compatible con Android 15 / ARMv9)

Configuración de ProGuard / R8

Si tu proyecto tiene minifyEnabled = true, agrega estas reglas a tu archivo proguard-rules.pro para garantizar que el SDK funcione correctamente, especialmente con el modo completo de R8 en AGP 8.x+.

¿Por qué son necesarias estas reglas?

AGP 8.x+ habilita por defecto el modo completo de R8, que elimina de forma agresiva las firmas de tipos genéricos. Sin -keepattributes Signature, el TypeToken<T> de Gson puede fallar en tiempo de ejecución con java.lang.Class cannot be cast to java.lang.reflect.ParameterizedType.
Última versión del SDKConsulta las notas de la versión o visita el repositorio del Yuno Android SDK para verificar la versión actual del SDK disponible.

Paso 1: crear un cliente

Crea un cliente con el endpoint Create customer antes de iniciar los pagos. Este paso es necesario para:
  • Identificar a la persona que realiza el pago
  • Habilitar la función de métodos de pago guardados (si está habilitada)
  • Hacer seguimiento del historial de pagos
El ID del cliente devuelto por 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 obtenido en el paso anterior
  • Guardar el ID de la checkout_session devuelto para usarlo en los pasos posteriores
La checkout_session es única para cada intento de pago y no se puede reutilizar.

Paso 3: incluir la biblioteca en tu proyecto

Incluye el Yuno SDK en tu proyecto mediante Gradle. Agrega el origen del repositorio:
Agrega la dependencia del Yuno SDK a tu aplicación en el archivo build.gradle:
Yuno SDK incluye, por defecto, el permiso INTERNET, necesario para realizar solicitudes de red. <uses-permission android:name="android.permission.INTERNET" />

Paso 4: inicializar el headless SDK con la clave pública

Importa Yuno y proporciona una PUBLIC_API_KEY válida para inicializar el Headless SDK. Si no tienes tus credenciales de API, consulta la página Developers (Credentials) para ver cómo obtenerlas desde el Dashboard. Crea una aplicación personalizada si aún no lo has hecho. En el método onCreate() de la clase de tu aplicación, inicializa el SDK llamando a la función Yuno.initialize():
Para una explicación detallada del parámetro keepLoader y del manejo de errores obligatorio, consulta la Android Reference Guide.

Paso 5: iniciar el proceso de checkout

Llama a la función apiClientPayment después de que tu cliente seleccione un método de pago para iniciar el proceso de checkout. Esta función requiere parámetros de configuración e inicia la recopilación de la información necesaria para la autenticación 3DS y las herramientas de prevención de fraude configuradas en tu enrutamiento. La siguiente tabla describe los parámetros requeridos: El siguiente bloque de código muestra un ejemplo de la configuración de los parámetros:

Paso 6: generar el token

Después de recopilar la información del usuario, crea un token de un solo uso (OTT) con la función apiClientPayment.generateToken. Como es una función asíncrona, usa un bloque try/catch para gestionar los errores que puedan ocurrir. Los siguientes ejemplos muestran dos escenarios distintos para crear un token de un solo uso:
  1. Ejemplo 1: crea un token de un solo uso usando 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 usando la información de vaulted_token.

Beneficios de usar un vaulted token

Cuando usas un vaulted token con el SDK, se recopila toda la información de fraude de los proveedores que configuraste en el enrutamiento de tarjetas. Esta información se adjunta al token de un solo uso. También puedes agregar información de cuotas y un código de seguridad si el proveedor lo requiere. Ambos ejemplos llaman a generateToken, que está declarado en el companion object de ApiClientPayment. Agrega import com.yuno.sdk.ApiClientPayment.Companion.generateToken a tu archivo.
Example 1
Example 2
type en Detail es opcional. Si lo omites, Yuno detecta el tipo de tarjeta a partir del número de tarjeta. Envíalo solo si estás seguro, porque un tipo incorrecto puede causar un rechazo. La función apiClientPayment.generateToken es una función suspend. Llámala desde una corrutina (por ejemplo, lifecycleScope.launch). Devuelve un Map<String, Any?> que contiene la respuesta completa. El siguiente bloque de código muestra ejemplos de respuestas después de llamar a la función apiClientPayment.generateToken.
Example 1
Example 2
La respuesta del endpoint incluye el parámetro sdk_action_required, que define si son necesarias acciones adicionales. El siguiente bloque de código muestra un ejemplo de cómo leer la respuesta. generateToken y continueCardPayment están declarados en el companion object de ApiClientPayment, así que impórtalos de forma explícita:

Paso 7: crear el pago

Después de generar el token de un solo uso, crea el pago llamando al endpoint Create Payment. Incluye el token de un solo uso obtenido en el Paso 6 en el parámetro payment_method.token de tu solicitud. El siguiente bloque de código muestra un ejemplo de una solicitud de creación de pago:
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
  • En los flujos de pago que requieren interacción adicional con el SDK, sdk_action_required será true. Cuando esto ocurra, continúa con el Paso 8 para conocer los siguientes pasos

Paso 8: continuar el pago (si es necesario)

Cuando un pago creado desde tu backend requiere un paso adicional, como un desafío 3DS, la respuesta del endpoint Create Payment incluye:
  • Estado PENDING y subestado WAITING_ADDITIONAL_STEP
  • sdk_action_required = true
Llama a continueCardPayment para que el SDK reanude el pago. El SDK ejecuta internamente la acción pendiente, incluida la presentación del desafío 3DS, espera el resultado y entrega el estado final del pago a tu callback.

Firma de la función

Parámetros

Uso

Estados del pago

continueCardPayment es compatible solo con pagos CARD.

Funciones complementarias

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 que coincida con tu marca, o para configurar el loader.

Loader

La funcionalidad del loader se controla mediante el parámetro keepLoader en la data class YunoConfig, que está documentada en línea en la sección anterior de configuración del SDK.

Personalización del SDK

Puedes cambiar la apariencia del SDK para que coincida con tu marca. Para más información, consulta la página de personalización del SDK.
Accede a la app de demostraciónAdemás de los ejemplos de código proporcionados, puedes consultar el repositorio de Yuno para completar la implementación de los Yuno Android SDK.

Paso 9: continuar el pago (no compatible)

Falta de compatibilidad con dispositivos móvilesEl método getContinuePaymentAction y la configuración “Continue Payment” (necesarios para funciones como Passkey SCOF) no son compatibles actualmente con el Headless Android SDK.Si tu integración requiere estas funciones, considera usar el Full Checkout SDK o el Web Headless SDK como alternativa.

Gestión de errores

Gestiona en tu app los errores devueltos por el SDK, como pagos fallidos o errores de validación. Para los códigos de estado y de respuesta HTTP, consulta Status and response codes en la referencia de la API.