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.

Requisitos previos
Tu proyecto de Android debe cumplir los siguientes requisitos de hardware, sistema y herramientas de compilación:- Hardware y sistema operativo: Android 11.0 (API level 30) o superior, con una antena NFC activa y compatibilidad con Host Card Emulation (HCE).
- Servicios: Google Play Services debe estar disponible en el dispositivo.
- Arquitectura: arquitectura ARM de 64 bits (
arm64-v8a) o de 32 bits (armeabi-v7a). (Los emuladores x86 / x86_64 no son compatibles con las operaciones NFC contactless). - Requisitos de herramientas de compilación:
- Compile SDK:
compileSdk 35 - Java: Java 17
- Kotlin: 2.1.0 o superior
- Android Gradle Plugin (AGP): 8.6.0 o superior
- Gradle: 8.7 o superior
- Hilt: 2.56 o superior (si usas inyección de dependencias)
- Room: 2.7.0-alpha13 o superior (si usas Room en tu proyecto)
- Compile SDK:
Marcas compatibles: actualmente, Tap to Add funciona con el Tap SDK de Visa. La compatibilidad con Mastercard y otros esquemas de tarjeta se incorporará en versiones posteriores.
Rutas de integración
Puedes integrar Tap to Add de una de dos maneras:- Ruta A: inscripción automática con el Yuno Android SDK 3.x (recomendada): si ya usas el Full Checkout SDK de Yuno para Android, al agregar la dependencia
yuno-tapse habilita automáticamente el punto de entrada de Tap to Add en el formulario de inscripción, sin escribir código de interfaz. - Ruta B: Yuno Tap SDK independiente: si creas pantallas de inscripción personalizadas o una interfaz headless, integra
com.yuno.payments:yuno-tapdirectamente, ya sea con elYunoTapToAddButtonprediseñado o con tu propio botón que llame aYunoTapTransaction.start.
Ruta A: inscripción automática con el checkout completo
Al integrar el Yuno Android Universal SDK (3.0.0 o posterior), el SDK comprueba automáticamente si yuno-tap está presente en el classpath de ejecución. Si lo encuentra y el dispositivo es compatible con NFC, el SDK muestra la opción Tap to Add directamente dentro del formulario de inscripción de tarjeta.
- Agrega las dependencias
Agrega el Yuno Android SDK y el artefacto Yuno Tap al build.gradle.kts de tu módulo:
- Configura el manifiesto para dispositivos con API inferior a 30
El Yuno Tap SDK exige minSdk = 30. Si tu aplicación principal usa un minSdkVersion menor (por ejemplo, minSdk = 24), permite que el manifest merger continúe agregando una declaración tools:overrideLibrary en tu AndroidManifest.xml:
Flujo visual
1
Punto de entrada en el formulario de inscripción
Cuando
yuno-tap está incluido en el proyecto, el formulario de inscripción de tarjeta muestra el punto de entrada Tap to add encima de la captura manual de la tarjeta.
2
Solicitud de NFC contactless
Al seleccionar Tap to add se abre la interfaz animada de tap por NFC, que le pide al cliente que acerque su tarjeta contactless a la parte trasera del dispositivo.

3
Confirmación de éxito
Una vez que los datos de la tarjeta se leen y se cifran en el dispositivo, Yuno completa la inscripción de forma segura y devuelve una confirmación de éxito.

Ruta B: Yuno Tap SDK independiente
Si administras tu propia interfaz de captura de tarjetas o quieres ubicar de forma personalizada la acción de Tap to Add, usa la biblioteca independienteyuno-tap.
- Agrega la dependencia
Agrega yuno-tap a tu build.gradle.kts:
- Obtén la sesión de cliente
Antes de iniciar el flujo de tap, tu backend debe crear una sesión de cliente con la API servidor a servidor de Yuno:
customer_session. Pásalo a tu aplicación Android. El SDK no crea sesiones de cliente; solo consume una.
- Implementa un YunoTapController y crea un YunoTapConfig
YunoTapController es la interfaz que usa el SDK para informar a tu aplicación. onStatus recibe el único TapStatus final de cada transacción. showLoading es opcional y refleja el calentamiento único del SDK:
PROD_… es producción y SANDBOX_… es sandbox, y el segmento posterior al prefijo es la región (por ejemplo, PROD_us_…).
publicApiKey es opcional si tu aplicación ya llamó a YunoTap.initialize(context, publicApiKey) antes en el proceso. Si falta y el SDK nunca se inicializó, la transacción informa ERROR con NOT_INITIALIZED.
- Opción 1: YunoTapToAddButton listo para usar
La integración independiente de interfaz más sencilla usa YunoTapToAddButton, un composable de Jetpack Compose que muestra la entrada de Visa Tap to Add e inicia el flujo cuando se presiona:
YunoTapController. De forma predeterminada, el botón no muestra nada en dispositivos que no pueden hacer tap (hideWhenNotEligible = true). Funciona solo con Compose: en una pantalla basada en View, aloja el botón en un ComposeView o usa la Opción 2.
- Opción 2: inicia el flujo desde tu propio botón
Para un disparador personalizado, llama a start en la transacción. activity debe ser una ComponentActivity:
start comprueba la elegibilidad del dispositivo, inicializa el SDK de Visa en el primer uso, muestra su propia interfaz segura, lee la tarjeta por NFC e informa el resultado mediante onStatus. Solo se puede ejecutar una transacción a la vez. Para cerrar una transacción en curso, llama a transaction.cancel(); onStatus recibirá entonces CANCELED.
Manejo de resultados
onStatus se llama exactamente una vez por cada start(), en el hilo principal, con un TapStatus. Su status es un TapStatusCode y, según el código, incluye un outcome (TapOutcome) y/o un error (YunoTapError):
TapOutcome.Added incluye estas propiedades:
last4, issuerName y merchantCardAlias están disponibles desde yuno-tap 0.4.0. TapOutcome.Confirmed está reservado para Tap to Confirm y TapFlow.Add nunca lo produce.
Códigos de error
ConERROR, error.code es uno de YunoTapErrorCodes:
Un criterio razonable por defecto: permite que el cliente lo intente de nuevo con
NETWORK_ERROR, INIT_TIMEOUT y TRANSACTION_INTERRUPTED, y recurre a la captura manual de la tarjeta con los demás.
Con FAILED, error.code lleva el código del backend o de Visa tal cual:
Configuración de ProGuard y R8
Las reglas de conservación de ProGuard y R8 vienen dentro del artefactoyuno-tap y se aplican automáticamente a tu build de lanzamiento, por lo que no necesitas agregar ninguna. El Visa Tap SDK está integrado en yuno-tap: no agregues el AAR de Visa por separado.
Próximas funciones
- Tap to Confirm: la compatibilidad con la autenticación de tarjetas contactless durante las transacciones de checkout está prevista para futuras versiones del SDK. Actualmente, solo está activo Tap to Add (
TapFlow.Add) para la inscripción de tarjetas.