Lite SDK (Pago 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.

Esta página proporciona una guía del Lite SDK Yuno Lite SDK para pagos en Android. Este SDK ofrece un proceso de integración simplificado con la funcionalidad esencial de pago, por lo que es ideal para los comerciantes que:

• ¿Necesita una implementación rápida con requisitos mínimos de personalización?
• Desea centrarse principalmente en el procesamiento de pagos con tarjeta.
• Prefiere una interfaz de usuario lista para usar que gestione el flujo de pago

El Lite SDK incluye características principales como:

• Componentes de interfaz de usuario de pago prediseñados
• Procesamiento de pagos con tarjeta
• Manejo básico del estado de pago
• Gestión de errores esenciales

Para los comerciantes que necesiten funciones más avanzadas, como múltiples métodos de pago, interfaz de usuario personalizada o prevención avanzada del fraude, considere la posibilidad de 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 credenciales 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

📘

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 5 de la integración
• El objeto checkout_session Es único para cada intento de pago y no se puede reutilizar.

🚧

Manejo de retornos del navegador externo

Si su flujo de pago envía a los usuarios a un navegador externo (por ejemplo, para autenticación 3DS o redirecciones bancarias), asegúrese de configurar la callback_url al crear su sesión de pago. Para obtener una guía paso a paso sobre cómo gestionar la devolución a su aplicación, consulte Manejar el retorno del navegador externo (callback_url).

Paso 3: Incluye la biblioteca en tu proyecto

Incluye el archivo del SDK de Yuno en tu proyecto a través de Gradle. 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}'
}

Permisos

El SDK de Yuno incluye el INTERNET por defecto, necesario para realizar solicitudes de red.

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

Paso 4: Inicializar el SDK con la clave pública

Initialize el SDK:

1. Obtén tus claves API públicas desde el panel de control de Yuno
2. Crea una clase de aplicación personalizada si no tienes una
3. Inicialice el SDK llamando Yuno.initialize() en tu aplicación con el método onCreate() pasando su clave API y su configuración:

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

Usa la clase de datos YunoConfig para personalizar el comportamiento del SDK. Incluya esta configuración cuando llame a Yuno.initialize(). Las opciones disponibles son:

clase de datos YunoConfig(
    val cardFlow: CardFormType  CardFormType.ONE_STEP,
    val saveCardEnabled: Boolean  false,
    val cardFormDeployed: 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: establezcete en verdadero para ocultar el campo del nombre del titular de la tarjeta
)

La siguiente tabla describe cada opción de personalización:

También necesitas actualizar tu manifiesto para usar tu aplicación:

<application android:name=".CustomApplication"></application>

Paso 5: Iniciar el proceso de 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 Lite SDK:

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

La siguiente tabla describe los parámetros necesarios para iniciar la comprobación:

Estado de pago de devolución de llamada

El objeto callbackPaymentState es una función que devuelve el proceso de pago actual. El envío de esta función no es obligatorio si no necesita el resultado. El siguiente bloque de código muestra los posibles estados:

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 6: Iniciar el proceso de pago

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

iniciarPagoLite(
   paymentSelected: PaymentSelected,
   callbackOTT:(¿Cadena?) -> Unidad,
   callBackTokenWithInformation:OneTimeTokenModel?) -> Unidad,
   showPaymentStatus: Boolean,
)

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

Envía un parámetro adicional, que es el token bóveda y/o el tipo de pago que el usuario seleccionó para realizar el pago:

PaymentSelected(
 vaultedToken : Stringpago",
 paymentMethodType : Cadenapago",
)

Paso 7: Consigue el OTT (token de un solo uso)

El token de un solo uso es un identificador único que representa una sesión de pago. Este token es necesario para crear un pago.

Token de devolución de llamada de un solo uso

La devolución de llamada de token única devuelve los siguientes parámetros:

🚧

Manejo del cargador

El comerciante es responsable del manejo del cargador. Yuno ofrece una opción para utilizar nuestro cargador; sin embargo, el comerciante puede utilizar su propio cargador y deberá realizar las configuraciones correspondientes.

Paso 8: Crea el pago

Después de completar los pasos anteriores, cree un pago llamando al endpoint Crear pago desde su backend. Este endpoint requiere:

• El token único obtenido en el paso 7
• El objeto checkout_session obtenido en el paso 2

🚧

Continuar con la integración de métodos de pago

Yuno requiere que integres el continuePayment del SDK después de crear el pago porque ciertos métodos de pago asincrónicos requieren una acción adicional por parte del cliente para completarlo. La API le informará de este escenario a través del sdk_action_required de la respuesta, que se devolverá como verdadero. La yuno.continuePayment() La función mostrará las pantallas adicionales a los clientes, donde podrán realizar las acciones necesarias para completar el pago sin necesidad de que usted maneje cada escenario.

Para los métodos de pago que requieren acciones adicionales del cliente (como desafíos de autenticación 3DS) o procesamiento asincrónico (como transferencias bancarias), deberá integrar el SDK. continuePayment método después de crear el pago. La respuesta de la API Crear pago incluye un sdk_action_required campo que indica si este paso es necesario:

• Si el TRUE: Llamar yuno.continuePayment() para mostrar pantallas adicionales para acciones del cliente (por ejemplo, autenticación 3DS, páginas de redireccionamiento bancario)
• Si el FALSE: Omita este paso, ya que no se requiere interacción adicional con el cliente.

El siguiente bloque de código muestra cómo implementar el flujo de continuación de pago:

continuePayment(
   showPaymentStatus: Boolean = true
   checkoutSession: String? = null
   countryCode: String? = null,
   callbackPaymentState: ((String?) -> Unit)? = null
)

Enviar FALSE en el showPaymentStatus para mostrar sus pantallas de estado de pago. A continuación, obtener el estado de pago por devolución de llamada.

Modo de renderizado (integración avanzada)

Para los desarrolladores que requieren un control avanzado de la interfaz de usuario, el SDK Lite también admite la integración del modo de renderizado. Este modo proporciona componentes de interfaz de usuario basados en fragmentos que se pueden integrar en diseños personalizados, ofreciendo mayor flexibilidad y manteniendo la funcionalidad optimizada del SDK Lite.

Configuración básica del modo de renderizado

Usar startPaymentRender Para una integración avanzada de la interfaz de usuario:

fun Activity.startPaymentRender(
   checkoutSession: String? = null
   countryCode: String? = null
    ámbitoCoroutina: CoroutineScope,
   paymentSelected: PaymentSelected,
    oyente: YunoPaymentRenderListener,
): YunoPaymentFragmentController

Ejemplo de implementación

class PaymentActivity : Activity() {

    private lateinit var fragmentController: YunoPaymentFragmentController

    private fun initializeRenderMode() {
        fragmentController = startPaymentRender(
            checkoutSession = checkoutSessionId,
            countryCode = "US",
            coroutineScope = lifecycleScope,
            paymentSelected = PaymentSelected.CARD,
            listener = object : YunoPaymentRenderListener {
                override fun showView(fragment: Fragment) {
                    supportFragmentManager.beginTransaction()
                        .replace(R.id.payment_container, fragment)
                        .commit()
                }

                override fun returnOneTimeToken(oneTimeToken: String, additionalData: OneTimeTokenModel?) {
                    processPayment(oneTimeToken) {
                        fragmentController.continuePayment()
                    }
                }

                override fun returnStatus(resultCode: Int, paymentStatus: String) {
                    handlePaymentResult(paymentStatus)
                }

                override fun loadingListener(isLoading: Boolean) {
                    updateLoadingUI(isLoading)
                }
            }
        )
    }
}

Beneficios clave

• Integración de interfaz de usuario personalizada: Incrusta componentes de pago en tus diseños existentes
• Compatibilidad de fragmentos: Funciona tanto con XML como con Jetpack Compose.
• Control de flujo: Gestione manualmente el envío de formularios y la continuación del pago

🚧

Función avanzada

El modo de renderizado está diseñado para desarrolladores que necesitan una integración de interfaz de usuario personalizada. Para implementaciones más sencillas, utilice los métodos estándar del SDK Lite descritos en los pasos anteriores.

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 4, 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:

Personalización del SDK

Puede cambiar el aspecto del SDK para adaptarlo a su marca. Para obtener más información, consulte la página de personalización del SDK.

📘

App Demo

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