Seamless SDK (Pago Android)

Esta página proporciona una guía del Yuno Seamless SDK para pagos en Android.

👍

SDK recomendado

Recomendamos utilizar el  Android Seamless SDK para una experiencia de integración sin problemas. Esta opción ofrece una solución de pago flexible con componentes de interfaz de usuario predefinidos y opciones de personalización.

Este SDK es ideal para comerciantes que:

• ¿Quiere tener control sobre el flujo de pago mientras aprovecha los componentes de interfaz de usuario prediseñados?
• ¿Necesita personalizar la experiencia de pago manteniendo el cumplimiento de PCI?
• Requiere un equilibrio entre la velocidad de implementación y la personalización.

El Seamless SDK incluye características como:

• Componentes de interfaz de usuario de pago prediseñados con opciones de personalización
• Admite múltiples métodos de pago
• Manejo avanzado del estado de pago
• Gestión integral de errores

Los comerciantes que necesiten un control completo de la interfaz de usuario o funciones más avanzadas pueden utilizar nuestro Full SDK completo.

Requisitos

Antes de comenzar la integración de Yuno Android SDK, asegúrate de que tu proyecto cumple los requisitos técnicos. Además, asegúrate de que se cumplen los siguientes requisitos previos:

• Debes tener una cuenta Yuno activa.
• Necesitas tus credenciales de la API de Yuno (account_id, public-api-keyy private-secret-key), que puedes obtener en Sección de desarrolladores del panel de Yuno. Estas credenciales son necesarias para autenticar las solicitudes a la API de Yuno. La API se utiliza para:
  • Cree un customer, que se requiere antes de iniciar los pagos
  • Cree un checkout_session, que inicialice el flujo de pago
  • Crear el pago asociado a la sesión

📘

Verificar la versión del SDK

Consulte las notas de la versión o el repositorio Yuno Android SDK para verificar la versión actual del SDK disponible.

Paso 1: Crea un cliente

Cree un cliente utilizando el endpoint Crear cliente antes de iniciar los pagos. Este paso es necesario para:

• Identificar a la persona que realiza el pago
• Habilitar la funcionalidad de tarjeta guardada (si está habilitada)
• Seguimiento del historial de pagos

El ID de cliente devuelto desde este endpoint se utilizará al crear el checkout_session.

Paso 2: Crea una sesión de pago

Crear un nuevo checkout_session utilizando la función del endpoint Crear sesión de pago para inicializar el flujo de pago. Asegúrese de que:

• Incluya el ID de cliente obtenido en el paso anterior
• Almacenar lo devuelto checkout_session ID para usar en el paso 6 de la integración

💳

Controlar la autenticación frente a la captura mediante el envío payment_method.detail.card.capture en la sesión de pago: false = solo autorizar, true = capturar inmediatamente.

Parámetros clave

🚧

Uso de la sesión de pago

El objeto checkout_session es único para cada intento de pago y no se puede reutilizar.

Paso 3: Agrega el SDK a tu proyecto

Añade la fuente del repositorio:

maven { url "https://yunopayments.jfrog.io/artifactory/snapshots-libs-release" }

Incluya el siguiente código en el archivo build.gradle para añadir la dependencia del SDK de Yuno a la aplicación:

dependencies {
    implementation 'com.yuno.payments:android-sdk:{last_version}'
}

Paso 4: Configurar permisos

El SDK de Yuno requiere permisos de red. Asegúrese de que el permiso INTERNET está incluido en su AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />

Paso 5: Inicializar el SDK

Recupera tus claves API públicas del panel de control de Yuno.

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):

class CustomApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        Yuno.initialize(
            this,
            PUBLIC_API_KEY,
            config = YunoConfig()
        )
    }
}

Use el endpoint YunoConfig para establecer configuraciones adicionales para el SDK. La siguiente tabla enumera y describe las opciones de personalización:

El siguiente bloque de código muestra un ejemplo de YunoConfig:

clase de datos YunoConfig(
    val cardFlow: CardFormType  CardFormType.ONE_STEP,
    val saveCardEnabled: Boolean  false,
    val language: YunoLanguage? = null,
      val styles: YunoStyles? = null,
    val cardNumberPlaceholder: String? = null, // Opcional: texto de marcador de posición personalizado para el campo del número de tarjeta
    val hideCardholderName: Boolean? = null // Opcional: establecer en verdadero para ocultar el campo del nombre del titular de la tarjeta
)

Paso 6: Iniciar el pago

Llame al startCheckout método en el onCreate() función de la actividad que integra el SDK para iniciar un nuevo proceso de pago con el Seamless SDK:

startCheckout(
 checkoutSession: "checkout_session",
  country_code: "US",
 callbackPaymentState: ((String?) -> Unit)?,
  merchantSessionId: String? = null
)

Los posibles estados de pago devueltos por callbackPaymentState son:

const val pago=SUCCEEDED"
const val pago= "FALLIDO"
const val pago= "PROCESANDO"
const val pago= "RECHAZAR"
const val pago= "ERROR_INTERNO"
const val pago= "CANCELADO"

La siguiente tabla proporciona información adicional sobre los posibles estados:

Validación pago

En esta sección se explica cómo gestiona el SDK pago cuando los usuarios cancelan o abandonan pago , y cómo se relaciona el estado del SDK con pago del backend en estos casos.

Sincronizar pago (Google Pay)

En el caso de pago sincrónicos, como Google Pay, cuando tú cancelas o cierras la interfaz de usuario de la cartera antes de recibir la respuesta del proveedor pago (PSP):

• Estado del SDK: Devoluciones CANCELED (CANCELLED)
• pago en el backend: Restos PENDING hasta el tiempo de espera de PSP o la cancelación por parte del comerciante
• ImportanteEl SDK no devolverá REJECT o PROCESSING en este escenario

Esto garantiza que el pago backend pago en estado pendiente y pueda ser gestionado correctamente por el sistema del comerciante.

pago asíncronos (métodos basados en PIX y QR)

Para pago asíncronos como PIX, cuando tú cierras la ventana del código QR (haces clic en X) antes de completar el pago:

• Estado del SDK: Devoluciones PROCESSING, opcionalmente con un subestado como CLOSED_BY_USER
• pago en el backend: Restos PENDING y el código QR sigue siendo válido hasta su fecha de caducidad.
• Reutilización de la sesión de pago: al volver a abrir la misma sesión de pago, se puede mostrar el mismo código QR válido.
• Sin cancelación automática: El pago PIX no pago cancela automáticamente cuando tú cierras la ventana QR.

Este comportamiento permite a los usuarios volver al pago y completar la transacción utilizando el mismo código QR antes de que caduque.

Pagos asíncronos caducados

Si un código QR PIX caduca de forma natural:

• Estado del backendActualizado a EXPIRED
• Estado del SDK: Las devoluciones de llamada del SDK y endpoints de sondeo endpoints EXPIRED de manera constante

Esto garantiza que los comerciantes reciban información precisa sobre el estado cuando un pago ha caducado.

Paso 7: Reciba el pago mediante un token de un solo uso (OTT)

Llamar al método startPaymentSeamlessLite para iniciar un proceso de pago:

startPagoSeamlessLite(
    pagoSeleccionado: PagoSeleccionado,
    callbackPaymentState: ((¿Cadena?) -> Unidad)?,
    showPaymentStatus: Boolean,
)

La siguiente tabla describe los parámetros para iniciar el pago:

Recibirá el estado del pago a través de callbackPaymentState, que indicará si el pago fue exitoso o si ocurrió algún problema.

Paso 8: Crear pago

Llamar al método startPaymentSeamlessLite con el método de pago seleccionado para completar el proceso de pago:

startPagoSeamlessLite(
    pagoSeleccionado: PagoSeleccionado,
    callbackPaymentState: ((¿Cadena?) -> Unidad)?,
    showPaymentStatus: Boolean,
)

Características complementarias

Yuno Android SDK proporciona servicios y configuraciones adicionales que puedes utilizar para mejorar la experiencia de los clientes. Utiliza la personalización del SDK para cambiar la apariencia del SDK para que coincida con tu marca o para configurar el cargador.

styles

Con el styles puede definir estilos visuales globales a través de una opción de personalización YunoStyles objeto. Permite aplicar una imagen de marca consistente en todo el SDK personalizando la apariencia y la tipografía de los botones.

datos clase YunoStyles(
    val BotónEstilos: YunoButtonStyles? = null,
    val fontFamily: ¿FontFamily? = null
)

El objeto YunoButtonStyles El objeto le permite definir configuraciones específicas para la apariencia del botón:

datos clase YunoButtonStyles(
    val backgroundColor: Color? = null,
    val contentColor: Color? = null,
    val cornerRadius: ¿Dp? = null
    val elevación: ¿Dp? = null
    val relleno: ¿Dp? = null
    val fontFamily: FontFamily? = null
    val fontSize: TextUnit? = null
    val fontStyle: FontStyle? = null
)

Use el endpoint YunoConfig descrita en el paso 5, para utilizar la clase de datos styles opción de personalización.

Loader

La funcionalidad del cargador se controla a través del keepLoader en el parámetro YunoConfig que se documenta en línea en la sección de configuración del SDK.

Guardar tarjeta para futuros pagos

También puede mostrar una casilla para guardar o inscribir tarjetas mediante cardSaveEnable: true. En los siguientes ejemplos se muestra la casilla de verificación para ambas variantes de representación del formulario de tarjeta:

Opciones de renderizado

Puede elegir entre dos opciones de representación de la forma de la tarjeta. Las siguientes capturas de pantalla muestran la diferencia entre cardFormType ONE_STEP y STEP_BY_STEP:

📘

Acceso a la aplicación de demostración

Además de los ejemplos de código proporcionados, puedes ver el repositorio de Yuno para completar la implementación de Yuno Android SDKs.