Saltar al contenido principal
Integra el SDK de Flutter de Yuno para los flujos Lite de pago e inscripción siguiendo estos pasos.

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.
  • FlutterFragmentActivity para MainActivity en 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 archivo android/build.gradle a nivel de proyecto:
Usa FlutterFragmentActivity en MainActivity.kt:
Crea una Application personalizada e inicializa el SDK nativo:
Luego registra la clase de la aplicación en 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 mediante IosConfig 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.
1

Crea un cliente y una sesión de checkout

Antes de iniciar un pago, crea un cliente y una sesión de checkout usando la API de servidor de Yuno.
  • 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_session devuelto para los siguientes pasos.
2

Inicializa el SDK

Inicializa el Yuno SDK en tu app de Flutter, normalmente antes de runApp en main.dart.
3

Inicia el proceso de checkout

Configura un listener de pagos (por ejemplo, YunoPaymentListener) en el árbol de widgets para recibir eventos.
4

Inicia el pago

Inicia el flujo de pago Lite llamando a startPaymentLite con el método de pago seleccionado.
5

Obtén el OTT (token de un solo uso)

Después de que el usuario complete el formulario, el SDK genera un OTT que se entrega a tu YunoPaymentListener.
6

Crea el pago

Usa el OTT del paso 5 para crear el pago en tu backend mediante el endpoint Create payment.
7

Continúa el pago

Si la respuesta incluye 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 PENDING hasta que se agote el tiempo de espera del PSP o el comercio cancele el pago
  • Importante: en este escenario, el SDK no devolverá reject ni processing

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 PENDING y 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: cancelByUser significa que el comprador salió de la pantalla, no que el pago falló. Confirma el estado final mediante un webhook o GET /v1/payments/{payment_id} antes de mostrar una cancelación.
* Los métodos de pago que muestran un código de pago o un comprobante (código QR de PIX, boleto, OXXO y similares), y Pix Parcelado, devuelven 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 EXPIRED de forma consistente

Lectura del mensaje de estado y del subestado

Desde yuno 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:
Los mismos campos están disponibles en 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.
Tanto 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.
1

Crea el cliente y la sesión

Crea un cliente y una customer_session en tu backend usando el endpoint Create customer session.
2

Inicializa el SDK

Asegúrate de que el SDK esté inicializado con tu clave de API y la configuración.
3

Inicia el proceso de inscripción

Configura un YunoEnrollmentListener para recibir actualizaciones de estado.
4

Inicia la inscripción

Llama a enrollmentPayment con el ID de la sesión del cliente.
5

Escucha el estado

Monitorea el estado de la inscripción mediante el callback de tu listener.
6

Gestiona los deep links (opcional)

Para los métodos que usan autenticación externa, pasa la URL de redirección al SDK. Consulta Gestión del retorno del deeplink para saber cómo capturar uri.
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 a Yuno.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:
  • YunoConfig para el idioma, el guardado de tarjetas y el manejo del loader
  • IosConfig.appearance para 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ámetro IosConfig.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

Cuando uses 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 mediante YunoSdkAndroidPlugin.initSdk().

YunoConfig (Android)

El SDK de Android admite un estilo completo mediante la clase de datos YunoConfig:
cardFlow se eliminó de YunoConfig (Android 2.11.0+)La configuración del flujo de tarjeta ahora se gestiona exclusivamente mediante el CheckoutBuilder en el Dashboard. Omite cardFlow en YunoConfig.

YunoStyles

Controla la apariencia visual de los componentes del SDK:

YunoButtonStyles

Ajusta con precisión la apariencia de los botones con estas opciones:
Configura los estilos en tu clase 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). Usa --dart-define para evitar escribir las claves directamente en el código:
Luego léela en Dart:
Si también necesitas la clave en el lado nativo de Android, asigna 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 paymentMethodType seleccionado.
  • Usa YunoPaymentListener/YunoEnrollmentListener para 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 de YunoLanguage: 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).