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 SDK para la inscripción en Android. El Yuno Headless SDK para Android ofrece una solución flexible y sin interfaz de usuario para inscribir métodos de pago y tokenizar tarjetas. Este SDK ofrece control total sobre el proceso de inscripción de métodos de pago, por lo que es ideal para los comercios que:
  • Necesitan control total sobre la interfaz y la experiencia de usuario
  • Quieren implementar flujos de inscripción personalizados
  • Requieren capacidades de integración avanzadas
El Headless SDK incluye funciones principales como:
  • Tokenización de tarjetas
  • Inscripción segura de métodos de pago
  • Acceso directo a la API
  • Manejo de errores personalizado
Si necesitas una solución con interfaz prediseñada o una integración más sencilla, considera usar otras implementaciones de SDK de Yuno:

Requisitos

Antes de iniciar la integración del Yuno Android SDK, asegúrate de que tu proyecto cumpla los requisitos técnicos:
  • Versión mínima del SDK: minSdkVersion 23 o superior (Android 6.0). Obligatoria 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
  • Compatibilidad con el tamaño de página ELF: cumple los requisitos de alineación de página ELF de 16 KB de Google (listo para Android 15 / ARMv9)

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 de 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.
Información sobre la versión del SDKVerifica la versión actual del SDK en las Notas de la versión o visitando el repositorio del Yuno Android SDK.

Paso 1: crea un cliente

Crea un cliente con el endpoint Create Customer antes de inscribir métodos de pago.

Paso 2: crea una sesión de cliente

Crea un nuevo customer_session con el endpoint Create Customer Session:
  • Incluye el ID del cliente en la solicitud
  • Guarda el ID de customer_session devuelto
  • Genera un nuevo customer_session para cada inscripción de método de pago.

Paso 3: agrega el SDK a tu proyecto

  1. Agrega la fuente del repositorio:
  1. Agrega la dependencia del SDK:
Se requiere el permiso de InternetEl Yuno SDK incluye automáticamente el permiso INTERNET, necesario para las solicitudes de red. Asegúrate de que tu AndroidManifest.xml contenga:<uses-permission android:name="android.permission.INTERNET" />

Paso 4: inicializa el Headless SDK con la clave pública

Obtén tus claves de API públicas en el Yuno Dashboard. Si no has implementado una aplicación personalizada, crea una. En el método onCreate() de tu clase de aplicación, llama a la función de inicialización (Yuno.initialize):

Paso 5: crea un objeto de método de pago de inscripción

Crea un objeto de método de pago de inscripción con el endpoint Enroll Payment Method para configurar la integración del Headless SDK para la inscripción. Al crear este objeto, especifica en qué tipo de método de pago puede inscribirse tu cliente. Actualmente, el Headless SDK solo admite el tipo de método de pago CARD.
Verificación de tarjetaPara verificar tarjetas (autorización de valor cero) antes de la inscripción, incluye el objeto verify al crear el objeto de método de pago para la sesión de cliente.

Paso 6: inicia el proceso de inscripción

Usa la función apiClientEnroll para iniciar el proceso de inscripción. Esta función requiere parámetros de configuración que definen cómo se procesará la inscripción. La siguiente tabla describe los parámetros obligatorios: El siguiente bloque de código muestra un ejemplo de la configuración de los parámetros:

Paso 7: genera un vaulted token

Después de recopilar toda la información obligatoria del cliente, crea un vaulted_token con la función apiClientEnroll.continueEnrollment. Como es una función asíncrona, usa un bloque try/catch para gestionar los errores que puedan ocurrir. El siguiente ejemplo muestra cómo crear un vaulted_token:
type en Detail es opcional. Si lo omites, Yuno detecta el tipo de tarjeta a partir del número de tarjeta. Si lo envías, se guarda con la tarjeta y se usa en pagos posteriores, por lo que un tipo incorrecto puede causar rechazos. La función apiClientEnroll.continueEnrollment es una función suspend. Llámala desde una corrutina (por ejemplo, lifecycleScope.launch). Devuelve un Map<String, Any?> con la respuesta completa. A continuación se muestra un ejemplo de respuesta al llamar a apiClientEnroll.continueEnrollment:
El siguiente bloque de código muestra un ejemplo de cómo leer la respuesta. continueEnrollment se declara en el companion object de ApiClientEnroll, por lo que debes importarlo de forma explícita:

Estados del flujo de inscripción

La función apiClientEnroll.continueEnrollment devuelve una respuesta que incluye un campo status que indica el estado actual del proceso de inscripción. Estos son los posibles estados devueltos:
La siguiente tabla ofrece información adicional sobre los posibles estados:
Seguimiento del estado mediante webhooksConsidera usar el estado de la inscripción recibido mediante Webhooks. Yuno recomienda basar siempre en este estado las decisiones de negocio en tu plataforma.

Manejo 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 HTTP y de respuesta, consulta Códigos de estado y de respuesta en la referencia de la API.