Requisitos
- Flutter SDK instalado (Dart incluido).
- iOS 14.0 o superior.
- Android minSdkVersion 21 o superior.
- Java 8 habilitado y AndroidX habilitado.
- Android Gradle plugin 4.0.0 o superior.
- Proguard 6.2.2 o superior.
- Kotlin Gradle plugin 1.4.0 o superior.
FlutterFragmentActivityparaMainActivityen Android.
Agregar el SDK a tu proyecto
Esta sección aplica a los flujos de pago y de inscripción. Completa estos pasos antes de implementar cualquiera de los dos flujos.Paquete de Flutter
Agrega el paquete de Yuno a tu proyecto de Flutter:Configuración de Android
Agrega el repositorio Maven de Yuno al archivoandroid/build.gradle a nivel de proyecto:
FlutterFragmentActivity en MainActivity.kt:
Application personalizada e inicializa el SDK nativo:
AndroidManifest.xml:
Configuración de iOS
No se requiere ninguna configuración adicional específica de iOS más allá de la instalación del paquete de Flutter. La personalización de la apariencia en iOS se configura medianteIosConfig durante la inicialización del SDK (consulta la sección Personalizaciones).
Pago
Sigue estos pasos para integrar el flujo de pago de Yuno en tu app de Flutter.Crea un cliente y una sesión de checkout
- Usa Create customer para representar a la persona que realiza el pago.
- Usa Create checkout session para definir los detalles de la transacción.
Conserva el ID
checkout_sessiondevuelto para los siguientes pasos.
Inicializa el SDK
runApp en main.dart.Inicia el proceso de checkout
YunoPaymentListener) en el árbol de widgets para recibir eventos.Inicia el pago
startPaymentLite con el método de pago seleccionado.Obtén el OTT (token de un solo uso)
YunoPaymentListener.Crea el pago
Continúa el pago
sdk_action_required: true, llama a continuePayment para gestionar 3DS o redirecciones.Validación del estado del pago
El SDK gestiona la relación entre el estado del SDK en el frontend y el estado del pago en el backend cuando los usuarios interactúan con los flujos de pago. Entender esta diferencia te ayuda a manejar correctamente los estados del pago en tu app.Métodos de pago sincrónicos (Apple Pay y Google Pay)
En los métodos de pago sincrónicos como Apple Pay y 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
cancelByUser(CANCELLED_BY_USER) - Estado del pago en el backend: permanece en
PENDINGhasta que se agote el tiempo de espera del PSP o el comercio cancele el pago - Importante: en este escenario, el SDK no devolverá
rejectniprocessing
Métodos de pago asincrónicos (PIX y métodos basados en QR)
En los métodos de pago asincrónicos, cuando un usuario cierra la ventana de pago antes de completarlo:- Estado del SDK: devuelve
cancelByUser*. - Estado del pago en el backend: permanece en
PENDINGy 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 se puede mostrar 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:
cancelByUsersignifica que el comprador salió de la pantalla, no que el pago falló. Confirma el estado final mediante un webhook oGET /v1/payments/{payment_id}antes de mostrar una cancelación.
processing con el subestado CLOSED_BY_USER en lugar de cancelByUser cuando el usuario cierra la pantalla. El pago permanece en PENDING en el backend y todavía se puede completar.Pagos asincrónicos 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 polling devuelven
EXPIREDde forma consistente
Lectura del mensaje de estado y del subestado
Desdeyuno 1.0.19 (SDK nativo de Android 2.22.0 / iOS 2.23.1), los resultados de pago e inscripción incluyen detalles adicionales que puedes leer desde el state del listener, junto con el estado:
YunoEnrollmentListener mediante state.enrollmentStatus, state.substatus y state.message.
state.message (YunoStatusMessage?)
state.substatus (String?)
Un estado más detallado. En iOS se asigna a Yuno.Result.substatus; en Android, al valor nativo PaymentSubStates (por ejemplo, CLOSED_BY_USER). Es null cuando la capa nativa no proporciona uno, incluida la inscripción en Android.
state.message solo se completa cuando la transacción es declined o rejected, o cuando el estado es un error interno. Para cualquier otro resultado (como un pago exitoso o en procesamiento) es null.message como substatus pueden ser null, por lo que siempre verifica que no sean nulos antes de usarlos.
Inscripción
Sigue estos pasos para inscribir métodos de pago en tu app de Flutter.Crea el cliente y la sesión
customer_session en tu backend usando el endpoint Create customer session.Inicializa el SDK
Inicia el proceso de inscripción
YunoEnrollmentListener para recibir actualizaciones de estado.Inicia la inscripción
enrollmentPayment con el ID de la sesión del cliente.Escucha el estado
Gestiona los deep links (opcional)
uri.Gestión del retorno del deeplink
Los métodos basados en redirección (algunos APM, 3DS externo e inscripción con autenticación externa) sacan al usuario de tu app y lo devuelven mediante un deeplink. Captura esa URL de retorno y pásala aYuno.receiveDeeplink. Esto aplica tanto al flujo de pago como al de inscripción.
Escucha los enlaces entrantes (por ejemplo, con el paquete app_links) y pasa la URL a Yuno.receiveDeeplink. Gestiona tanto el enlace de arranque en frío (la app se abrió desde el deeplink) como los enlaces recibidos mientras la app ya está en ejecución.
Parámetros
Para ver la lista completa de parámetros y opciones, consulta las subsecciones siguientes.Yuno.init
YunoConfig
IosConfig
Appearance (iOS)
StartPayment (Lite)
MethodSelected
EnrollmentArguments
Personalizaciones
Puedes personalizar el comportamiento y la apariencia del SDK usando las opciones de configuración:YunoConfigpara el idioma, el guardado de tarjetas y el manejo del loaderIosConfig.appearancepara el estilo de la interfaz en iOS- El estilo en Android mediante la configuración nativa (consulta más abajo)
Personalización en iOS
La apariencia en iOS es totalmente personalizable mediante el parámetroIosConfig.appearance en Yuno.init(). Puedes modificar el estilo visual para que coincida con la identidad de tu marca, incluidos los colores, las fuentes y el diseño de los botones.
Opciones de personalización disponibles en iOS
Color(0xFF...) para la personalización de la apariencia en iOS, agrega import 'dart:ui'; al inicio de tu archivo.
Para ver más opciones de personalización en iOS, consulta Personalizaciones del SDK (iOS).
Personalización en Android
En Android, el SDK de Flutter usa el sistema de estilos del SDK nativo de Android. La personalización se realiza en la capa nativa de Android con código Kotlin/Java al inicializar el SDK medianteYunoSdkAndroidPlugin.initSdk().
YunoConfig (Android)
El SDK de Android admite un estilo completo mediante la clase de datosYunoConfig:
YunoStyles
Controla la apariencia visual de los componentes del SDK:YunoButtonStyles
Ajusta con precisión la apariencia de los botones con estas opciones:Application durante la inicialización del SDK en MyApp.kt. Para ver más opciones de personalización en Android, incluidos los temas XML y la personalización de drawables, consulta Personalizaciones del SDK (Android).
Variables de entorno (recomendado)
Usa--dart-define para evitar escribir las claves directamente en el código:
dart-defines a BuildConfig. Luego lee BuildConfig.YUNO_API_KEY en MyApp (consulta el README del SDK de Flutter para ver el fragmento completo).
Solución de problemas
Notas
- El flujo de pago Lite requiere que renderices la lista de métodos de pago y pases el
paymentMethodTypeseleccionado. - Usa
YunoPaymentListener/YunoEnrollmentListenerpara recibir las actualizaciones de OTT y de estado, y para impulsar las llamadas al backend.
Idiomas compatibles
El SDK de Flutter admite los siguientes valores deYunoLanguage:
en (inglés), es (español), pt (portugués), ms (malayo), id (indonesio), th (tailandés), ar (árabe), hi (hindi), bn (bengalí), ml (malayalam), ur (urdu).