Full SDK (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 para el Full SDK Yuno para Android, que ofrece una solución de pago completa con una interfaz de usuario personalizable. Proporciona funciones avanzadas como la gestión de métodos de pago, la prevención del fraude y flujos de pago sin fisuras, por lo que es más rico en funciones que nuestro Headless SDK, que es específico para las capacidades de procesamiento de pago básicas.

Requisitos

Antes de iniciar 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:

1. Debes tener una cuenta Yuno activa
2. 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 checkout_session, que inicialice el flujo de pago
• Crear el pago asociado a la sesión

3. Antes de crear un pago, debe crear un cliente utilizando el endpoint Crear cliente

Paso 1: Incluya la biblioteca en tu proyecto

Incluye el archivo SDK de Yuno en tu proyecto a través de Gradle. A continuación, añade la fuente del repositorio:

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

📘

Versión del SDK

Accede a las notas de la versión o al repositorio Yuno Android SDK para verificar la última versión disponible del SDK.

A continuación, 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, por defecto, el INTERNET permiso, que se requiere para realizar solicitudes de red.

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

Paso 2: Initialize el SDK con la clave pública

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,
      "<your-public-api-key>",
      config: YunoConfig,
    )
  }
}

📘

Credenciales

Para más información, consulte la página de credenciales: https://docs.y.uno/reference/authentication

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
)

Parámetros

La siguiente tabla describe cada una de las personalizaciones disponibles:

Actualice tu manifiesto para utilizar tu aplicación:

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

Paso 3: Crear la sesión de pago

Cada pago requiere un nuevo checkout_sessionque proporciona acceso a todos los métodos de pago disponibles para un cliente específico. Utiliza la función Crear sesión de pago para obtener un nuevo checkout_session. Esta sesión se utiliza entonces para iniciar el pago.

📘

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

Llame al startCheckout dentro del método onCreate() función de la actividad que inicializa el SDK para iniciar un nuevo proceso de pago con el Full SDK:

startCheckout(
 checkoutSession"checkout_session",
 countryCode: "código_país_iso",
 callbackPaymentState: ((String?) -> Unit)?,
  merchantSessionId: String? = null
)

Parámetros

Configura la caja con las siguientes opciones:

A continuación se indican los posibles estados devueltos por la función callbackPaymentState:

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 5: Añadir la vista SDK a la caja

Use el endpoint PaymentMethodListViewComponent para mostrar los métodos de pago disponibles al implementar el Full SDK con Jetpack Compose. Este componente proporciona callbacks para notificar a tu aplicación cuándo activar o desactivar el botón de pago, y cuando un método de pago inscrito se elimina correctamente.

Firma del componente

@Composable
fun PaymentMethodListViewComponent(
    activity: Activity,
    modifier: Modifier? = null,
    onPaymentSelected: (Boolean) -> Unit,
    onUnEnrollSuccess: (Boolean) -> Unit = {}
)

Parámetros

• activity: Activity
  • La corriente Activity Donde se aloja el componente. Necesario para gestionar correctamente los flujos de pago.
• modifier: Modifier? (opcional)
  • Le permite personalizar el diseño y la apariencia (por ejemplo, relleno, espaciado). El valor predeterminado es null.
• onPaymentSelected: (Boolean) -> Unit
  • Se invoca una devolución de llamada siempre que se selecciona o deselecciona un método de pago.
    • true → Se selecciona un método (habilitar el botón de pago).
    • false → No se ha seleccionado ningún método (desactivar el botón de pago).
• onUnEnrollSuccess: (Boolean) -> Unit (opcional)
  • Se invoca una devolución de llamada cuando se elimina con éxito (se cancela la inscripción) un método de pago almacenado.
    • true → Indica que la eliminación se realizó correctamente.
    • Se puede utilizar para mostrar una barra de refrigerio, actualizar la lista o actualizar el estado de la interfaz de usuario.

Ejemplo

val coroutineScope = recordarCoroutineScope()
val snackbarHostState = remember { SnackbarHostState() }
var paymentMethodIsSelected by remember { mutableStateOf(false) }

Columna(
    modificador = Modificador
        .peso(1f)
        .verticalScroll(rememberScrollState())
) {
    PaymentMethodListViewComponent(
        actividad = actividad,
       onPaymentSelected = { isSelected ->
            paymentMethodIsSelected = isSelected
        },
       onUnEnrollSuccess = { éxito ->
            if (éxito) {
                coroutineScope.lanzar {
                    snackbarHostState.showSnackbar(
                        mensaje = "Tu método de pago ha sido eliminado",
                    )
                }
            }
        },
    )
}

❗

Importante

Envuelva siempre el componente en un Column con .verticalScroll(rememberScrollState()). Sin esto, es posible que la lista de métodos de pago no se muestre o no se desplace correctamente cuando haya varios métodos disponibles.

Paso 6: Iniciar el proceso de pago

Llame al startPayment() para iniciar un proceso de pago:

iniciarPago(
    showStatusYuno: Boolean,
   callbackOTT: (¿Cadena?) -> Unidad = this:onTokenUpdated,
   callBackTokenWithInformation:OneTimeTokenModel?) -> Unidad = this:onTokenComplete

)

Parámetros

Configura el pago con las siguientes opciones:

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

Después de que el cliente rellene los datos solicitados en los formularios de pago de Yuno, obtendrás el token de un solo uso, un parámetro necesario para crear un pago utilizando la API de Yuno.

El token de un solo uso será compartido por Yuno usando la función callbackOTT que proporcionó en el paso 6 al iniciar el pago. El token de un solo uso estará disponible en el onActivityResult.

📘

Configuración del cargador

Mientras Yuno recibe la información del cliente y comparte el token de un solo uso, se puede mostrar un cargador para mejorar la experiencia del usuario. Yuno proporciona un cargador predeterminado listo para usar. Sin embargo, los comerciantes pueden implementar su propio cargador y son responsables de realizar las configuraciones necesarias.

Paso 8: Crea el pago

Tras recibir el token de un solo uso de Paso 7cree el pago utilizando la función Crearendpoint pago. Utiliza el checkout_session de Paso 3 y el token de un solo uso para crear el pago.

La respuesta del endpoint Create Payment incluirá el parámetro sdk_action_requiredque define si se requieren acciones adicionales para finalizar el pago en función del tipo de pago.

🚧

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

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

Paso 9: Seguir pago

Yuno requiere integrar el SDK de continuePayment después de crear el pago, ya que algunos métodos de pago asíncronos requieren acciones adicionales del cliente para completarse. La respuesta del método Crearendpoint pagoa partir del paso 8, incluirá un sdk_action_required campo. Si devuelve TRUEdebe llamar a la función continuePayment() para mostrar pantallas adicionales que permitan al cliente completar el pago. De lo contrario, este paso no es necesario. Llame a la función continuePayment :

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

Para mostrar sus pantallas de estado de pago, envíe FALSE en el showPaymentStatus . Luego, obtenga el estado del pago mediante devolución de llamada.

Integración del modo de renderizado

El modo de renderizado del SDK de Yuno proporciona una flexibilidad avanzada de la interfaz de usuario, permitiendo a los desarrolladores integrar flujos de pago con un control total sobre la interfaz de usuario, manteniendo al mismo tiempo la funcionalidad completa full SDK . Este modo devuelve fragmentos que se pueden utilizar tanto con Jetpack Compose como con las vistas XML tradicionales.

Función principal: startPaymentRender

El objeto startPaymentRender inicializa el flujo de pago en modo renderizado, dándole un control granular sobre la presentación de la interfaz de usuario.

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

Parámetros

Ejemplo de implementación

class PaymentActivity : Activity() {

    private lateinit var fragmentController: YunoPaymentFragmentController

    private fun initializePayment() {
        fragmentController = startPaymentRender(
            checkoutSession = "your_checkout_session_id",
            countryCode = "US",
            coroutineScope = lifecycleScope,
            paymentSelected = PaymentSelected.CARD,
            listener = paymentRenderListener
        )
    }
}

YunoPaymentRenderListener interfaz

Implementa esta interfaz para recibir todos los eventos y vistas del SDK durante el flujo de pago:

class PaymentRenderListener : YunoPaymentRenderListener {

    override fun showView(fragment: Fragment) {
        supportFragmentManager.beginTransaction()
            .replace(R.id.payment_container, fragment)
            .commit()
    }

    override fun returnStatus(resultCode: Int, paymentStatus: String) {
        when (paymentStatus) {
            "SUCCEEDED" -> handleSuccessfulPayment()
            "FAIL" -> handleFailedPayment()
        }
    }

    override fun returnOneTimeToken(oneTimeToken: String, additionalData: OneTimeTokenModel?) {
        createPaymentInBackend(oneTimeToken) { result ->
            when (result) {
                is Success -> fragmentController.continuePayment()
                is Error -> handlePaymentError(result.error)
            }
        }
    }

    override fun loadingListener(isLoading: Boolean) {
        progressBar.visibility = if (isLoading) View.VISIBLE else View.GONE
    }
}

YunoPaymentFragmentController interfaz

Controla el flujo de pago utilizando la instancia de controlador devuelta:

Métodos

• submitForm(): Presenta el formulario actual cuando está disponible
• continuePayment(): Continúa el flujo de pago tras el procesamiento OTT backend

fragmentController.submitForm()

fragmentControllercontinuePayment()

Ventajas de la integración

Flexibilidad de la interfaz de usuario

• Compatible con Compose y XML: Funciona tanto con Jetpack Compose como con las vistas XML tradicionales.
• Control total: Tú decides dónde y cómo mostrar cada vista
• Integración personalizada: Fácil integración con el diseño de la aplicación existente

Control del caudal

• Lógica de envío personalizada: Controla cuándo enviar los formularios
• Integración backend: Procese OTT en su backend antes de continuar

Ejemplo de integración completa

class PaymentActivity : ComponentActivity() {

    private lateinit var fragmentController: YunoPaymentFragmentController

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        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_fragment_container, fragment)
                        .commit()
                }

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

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

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

🚧

Gestión del ciclo de vida

Asegúrese de que el CoroutineScope está vinculado al ciclo de vida de la Actividad/Fragmento para evitar pérdidas de memoria y garantizar una limpieza adecuada.

Características complementarias

El SDK de Yuno para Android proporciona servicios y configuraciones adicionales que puedes utilizar para mejorar la experiencia del cliente. Utiliza las personalizaciones del SDK para cambiar su apariencia y adaptarla a tu marca o para configurar el cargador:

Click to Pay (CTP) con Passkey

A diferencia de otros procesos, cuando un usuario completa un pago utilizando CTP Passkey, el Token única (OTT) no se recibirán a través de los métodos habituales de devolución de llamada. La OTT se entregará a través del URL del enlace profundo en la Intención. Tu aplicación debe leerla desde el Intentcrea el pago en tu backend, y luego continúa el flujo con el SDK.

⚠️

Importante

Es esencial incluir un callback_url al crear la sesión de pago para los pagos con CTP Passkey. Esta URL debe coincidir con el esquema de enlace profundo configurado en tu AndroidManifest. Por ejemplo:

JSON

{
  "callback_url": "myapp://pay/ctp"
}

El objeto callback_url Se utiliza para redirigir al cliente de vuelta a tu aplicación una vez completado el proceso de autenticación con Passkey.

1. AndroidManifest (enlace profundo)

Añadir un intent-filter a su actividad principal en AndroidManifest.xml:

<activity android:name=".CheckoutActivity" android:exported="true">
  <intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <!-- Adjust to your actual scheme/host -->
    <data android:scheme="myapp" android:host="pay" android:pathPrefix="/ctp" />
  </intent-filter>
</activity>

Ajusta el scheme, hosty pathPrefix para que coincida con la configuración de tu aplicación.

2. Manejar la intención

En tu actividad, maneja la Intención en ambos onCreate() y onNewIntent():

class CheckoutActivity : AppCompatActivity() {
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        initYuno()
        startCheckout()
        // Initialize your SDK / UI
        handleDeeplink(intent)
    }

    override fun onNewIntent(intent: Intent) {
        super.onNewIntent(intent)
        setIntent(intent)
        handleDeeplink(intent)
    }

    private fun handleDeeplink(intent: Intent?) {
        val uri = intent?.data ?: return

        when {
            // Cancellation or error
            uri.getBooleanQueryParameter("has_error", false) -> {
                val message = uri.getQueryParameter("message") ?: "Operation canceled"
                showError(message)
            }

            // Success: OTT received in URL
            uri.getQueryParameter("one_time_token") != null -> {
                val ott = extractOtt(uri) ?: return
                val checkoutSession = extractCheckoutSession(uri)

                // 1) Send the OTT to your backend to create the payment
                createPaymentOnBackend(ott) { success ->
                    if (success && checkoutSession != null) {
                        // 2) Then continue the flow in the SDK
                        continuePayment(
                            checkoutSession = checkoutSession,
                            countryCode = currentCountry
                        ) { result ->
                            // Handle payment state
                        }
                    }
                }
            }
        }
    }
    
    private fun extractOtt(uri: Uri): String? =
        uri.getQueryParameter("one_time_token")

    private fun extractCheckoutSession(uri: Uri): String? =
        uri.getQueryParameter("checkout_session")
            ?: uri.getQueryParameter("checkoutSession")
}

3. Crear el pago (Backend)

Una vez extraído el OTT del enlace profundo, crea el pago en tu backend utilizando el endpoint Crear pago .

Tras recibir una respuesta satisfactoria de tu backendpago creado), continúa el flujo en el SDK llamando a continuePayment().

4. Funciones auxiliares

Crea funciones de ayuda para extraer parámetros de la URI de la Intención:

private fun extraerOtt(uri: Uri): ¿Cadena? =
    uri.getQueryParameter("one_time_token")

private fun extraerSesiónDePago(uri: Uri): ¿Cadena? =
    uri.getQueryParameter("sesión_salida")
        ?: uri.getQueryParameter(checkoutSession")

💡

Consejo

En entornos de control de calidad, registra la URL completa para verificar los nombres de los parámetros.

5. Pruebas rápidas

Puedes probar el flujo CTP Passkey utilizando estos ejemplos de URL de enlace profundo:

• Éxito: myapp://pay/ctp?one_time_token=OTT_123&checkout_session=CHK_456
• Error: myapp://pay/ctp?has_error=true&message=User%20canceled
• Continuación: myapp://pay/ctp

6. Lista de control

Utiliza esta lista de comprobación para garantizar la correcta integración de CTP Passkey:

• ✅ callback_url incluido al crear la sesión de pago (debe coincidir con el esquema de enlace profundo)
• ✅ intent-filter configurado correctamente (esquema/host/ruta)
• ✅ handleDeeplink implementado tanto en onCreate() y onNewIntent()
• ✅ Extrae ambos one_time_token y checkout_session parámetros
• ✅ Crear pago en backend con OTT ➜ llamada continuePayment(...)
• Mango has_error y message parámetros para escenarios de error

⚠️

Importante

La OTT no recibirse a través del callbackOTT para pagos CTP Passkey. En su lugar, debes extraer el token de los parámetros URI de la Intención.

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
)

Para utilizar el styles utiliza la opción YunoConfig clase de datos, descrita en el paso 2.

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

Puede mostrar una casilla para guardar o inscribir tarjetas utilizando 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:

Personalizaciones del SDK

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

📘

Aplicación de demostración

Además de los ejemplos de código proporcionados, puedes acceder al repositorio de Yuno para una implementación completa de Yuno Android SDKs.