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.
Visa Tap to Add permite a los clientes inscribir sus tarjetas contactless acercándolas a la antena NFC de su dispositivo Android.

Descripción general de Visa Tap to Add

La interacción de tap usa internamente el Thin Client Tap SDK de Visa: los datos de la tarjeta se leen directamente por NFC, se cifran en el dispositivo y se envían de forma segura a Yuno. La aplicación del comercio nunca accede a los números de cuenta primarios (PAN) en claro ni los gestiona.

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)
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:
  1. 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-tap se habilita automáticamente el punto de entrada de Tap to Add en el formulario de inscripción, sin escribir código de interfaz.
  2. Ruta B: Yuno Tap SDK independiente: si creas pantallas de inscripción personalizadas o una interfaz headless, integra com.yuno.payments:yuno-tap directamente, ya sea con el YunoTapToAddButton prediseñado o con tu propio botón que llame a YunoTapTransaction.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.
Solo inscripción: Tap to Add solo es compatible con la inscripción de tarjetas y con guardar métodos de pago en la cuenta de un cliente. Nunca se muestra durante el checkout, en flujos de pago únicos ni en pantallas de compra directa.

  1. Agrega las dependencias

Agrega el Yuno Android SDK y el artefacto Yuno Tap al build.gradle.kts de tu módulo:

  1. 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:
En dispositivos con Android 10 (API 29) o inferior, el Yuno SDK detecta la versión de la plataforma sin errores y oculta la opción Tap to Add, con lo que recurre a la captura manual de la tarjeta.

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.

Punto de entrada de Tap to Add en el formulario de 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.

Solicitud de tap por NFC

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.

Confirmación de tarjeta agregada


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 independiente yuno-tap.

  1. Agrega la dependencia

Agrega yuno-tap a tu build.gradle.kts:

  1. 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:
La respuesta devuelve un ID customer_session. Pásalo a tu aplicación Android. El SDK no crea sesiones de cliente; solo consume una.

  1. 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:
El SDK elige el entorno y la región a partir del prefijo de la clave de API pública, por lo que no hay un parámetro de entorno: 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.

  1. 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:
El resultado llega al mismo 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.

  1. 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

Con ERROR, 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 artefacto yuno-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.