> ## Documentation Index
> Fetch the complete documentation index at: https://docs.y.uno/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Test in the sandbox first: base URL https://api-sandbox.y.uno (Test Mode in the Dashboard). Production is https://api.y.uno (Live Mode).
> Every API request needs the public-api-key and private-secret-key headers. Get them in the Dashboard at https://dashboard.y.uno/developers (Developers > Credentials); sandbox and production keys are different.
> Send an X-Idempotency-Key (a UUID) when creating payments, refunds and cancels, so retries do not create duplicates.
> Start with the Quickstart (https://docs.y.uno/docs/quickstart.md) and the agent guide (https://docs.y.uno/agents.md). To search these docs from a coding agent, connect the docs MCP server at https://docs.y.uno/mcp.

# Referencia de Android

> Consulta todos los parámetros del SDK de Android, las opciones de YunoConfig y los métodos públicos de keepLoader

> [!NOTE]
>
> **Esta página documenta un SDK heredado.** ¿Vas a iniciar una nueva integración? Usa el [Yuno SDK](https://docs.y.uno/docs/yuno-sdk/get-started.md). ¿Ya usas un SDK heredado? Sigue la [guía de migración](https://docs.y.uno/docs/yuno-sdk/migration/overview.md).
>
> El nuevo **Yuno SDK** (Web v2.x, iOS v3.x, Android v3.x, React Native v2.x) reemplaza los SDK Full, Lite, Seamless, Render, Headless y Secure Fields con una sola API en todas las plataformas. Los SDK heredados siguen siendo compatibles en paralelo durante la transición y está previsto dejarlos de usar en **2027**. Contacta a tu Account Manager para planificar la migración.

Parámetros, personalizaciones y funciones avanzadas para todos los flujos del SDK de Android. Configuración: [Flujos de pago (Android)](https://docs.y.uno/docs/sdks/full-checkout/android-payments), [Flujos de inscripción (Android)](https://docs.y.uno/es/docs/sdks/card-enrollment/android-enrollment.md), [modos de integración](https://docs.y.uno/es/docs/sdks/overview/choose-integration.md).

## Parámetros clave (creación de la sesión de checkout)

Al crear una sesión de checkout en tu backend para los flujos de pago, los siguientes parámetros se usan con frecuencia en los SDK de Android:

| Parámetro | Obligatorio | Descripción |
| - | - | - |
| `amount` | Sí | El objeto del monto principal de la transacción, que contiene `currency` (código ISO 4217) y `value` (monto numérico en esa moneda). |
| `alternative_amount` | No | Una representación del monto de la transacción en otra moneda, con la misma estructura que `amount` (`currency` y `value`). Útil para escenarios multimoneda. Por ejemplo, puedes mostrar los precios a los clientes en su moneda preferida (por ejemplo, USD) mientras procesas el pago en la moneda local (por ejemplo, COP). |

## Parámetros de pago (referencia completa)

Parámetros para los flujos de pago. Todos los parámetros usados en [Flujos de pago (Android)](https://docs.y.uno/docs/sdks/full-checkout/android-payments) se enumeran aquí con todo detalle.

| Parámetro | Tipo | Obligatorio | Descripción |
| - | - | - | - |
| `checkoutSession` | string | Sí | ID de la sesión de checkout de tu backend (API Create checkout session). Obligatorio para todos los flujos de pago. |
| `countryCode` | string | Sí | Código de país ISO donde se ejecuta el pago (por ejemplo, `US`, `BR`). Determina los métodos de pago disponibles y el cumplimiento normativo. |
| `callbackPaymentState` | function | No | `((String?, String?, StatusMessage?) -> Unit)?`. Se invoca con el estado del pago (`SUCCEEDED`, `FAIL`, `PROCESSING`, `REJECT`, `INTERNAL_ERROR`, `CANCELED_BY_USER`), su subestado y, en los resultados de error, un [`StatusMessage?`](#statusmessage-error-details). El tercer parámetro se agregó en el SDK `2.22.0`. Úsalo para actualizar la UI, para analítica o para la navegación. |
| `merchantSessionId` | string | No | Identificador opcional de la sesión del comercio. Úsalo para correlacionar la sesión del SDK con tu propia sesión o con el ID de tu pedido. |
| `onInstallmentSelected` | function | No | Callback que se invoca cuando el comprador selecciona una opción de cuotas en el formulario de tarjeta (payload `InstallmentSelected?` con `installment`, `label` y `amount`). Se activa con la preselección predeterminada, con cada selección, con los recálculos del plan y una vez con `null` cuando las cuotas dejan de estar disponibles. Disponible desde el SDK `2.20.0`. Consulta [Full (Android)](https://docs.y.uno/docs/sdks/full-checkout/android-payments#installment-selection-callback-oninstallmentselected). |

## Opciones de YunoConfig (inicialización)

El comportamiento en tiempo de ejecución y la apariencia se configuran mediante la clase de datos `YunoConfig` al llamar a `Yuno.initialize(context, apiKey, config)`. A continuación se enumeran todos los parámetros usados en los flujos de pago e inscripción de Android. Para el estilo visual (fuentes, colores, botones), consulta [Personalizaciones del SDK (Android)](https://docs.y.uno/es/docs/sdks/customization/android.md).

| Parámetro | Tipo | Obligatorio | Descripción |
| - | - | - | - |
| `saveCardEnabled` | boolean | No | Cuando es `true`, permite que el usuario guarde o inscriba la tarjeta durante el pago. Requiere compatibilidad del backend con el almacenamiento seguro (vaulting), por ejemplo, `payment_method.vault_on_success` en la sesión de checkout. |
| `keepLoader` | boolean | No | Si es `true`, el indicador de carga del SDK permanece visible desde la generación del OTT hasta que se llama a `continuePayment()`. Esto evita parpadeos en la UI. Si falla la creación del pago, llama a `hideLoader()` para ocultarlo manualmente. |
| `language` | `YunoLanguage` | No | Idioma de la UI del SDK, como un valor del enum `YunoLanguage` (por ejemplo, `YunoLanguage.ENGLISH`, `YunoLanguage.SPANISH`). Consulta [Idiomas compatibles](https://docs.y.uno/es/docs/sdks/resources/languages-supported.md). |
| `styles` | object | No | Estilos personalizados que se aplican a los elementos de la UI del SDK. Define los estilos en tu app y haz referencia a ellos aquí, o usa sobrescrituras del tema. Consulta [Personalizaciones del SDK (Android)](https://docs.y.uno/es/docs/sdks/customization/android.md) para las opciones de fuente, botón y color. |

## Parámetros de inscripción (referencia completa)

Parámetros para los flujos de inscripción. Todos los parámetros usados en [Flujos de inscripción (Android)](https://docs.y.uno/es/docs/sdks/card-enrollment/android-enrollment.md) se enumeran aquí con todo detalle.

| Parámetro | Tipo | Obligatorio | Descripción |
| - | - | - | - |
| `customerSession` | string | Sí | ID de la sesión de cliente de la API Create customer session. Obligatorio. Asocia el método de pago inscrito con un cliente específico. |
| `countryCode` | string | Sí | Código de país ISO (por ejemplo, `US`, `BR`). Obligatorio para la inscripción. |
| `showEnrollmentStatus` | boolean | No | Cuando es `true`, muestra la pantalla de resultado de la inscripción al terminar el flujo. El valor predeterminado es `true`. Configúralo en `false` para gestionar el resultado solo mediante el callback. |
| `callbackEnrollmentState` | function | No | `((String?, StatusMessage?) -> Unit)?`. Se invoca con el estado de la inscripción y, en `INTERNAL_ERROR`, un [`StatusMessage?`](#statusmessage-error-details). El segundo parámetro se agregó en el SDK `2.22.0`. Requiere registrar `initEnrollment` en el `onCreate` de tu Activity (o equivalente). |

## Métodos públicos

Los siguientes métodos están disponibles globalmente mediante el objeto `Yuno` o como extensiones de `Activity`.

### `Activity.hideLoader()`

Oculta el indicador de carga del SDK cuando `keepLoader` está activo. Usa este método cuando falle la creación del pago en tu backend. También es útil cuando no puedes continuar con `continuePayment()`.

```kotlin theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
fun Activity.hideLoader()
```

### `Yuno.continuePayment()`

Reanuda el flujo de pago para los métodos asíncronos (3ds, PIX, etc.) después de que se haya creado un pago en tu backend.

```kotlin theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
fun continuePayment(
    showPaymentStatus: Boolean = true,
    checkoutSession: String? = null,
    countryCode: String? = null,
    callbackPaymentState: ((String?, String?, StatusMessage?) -> Unit)? = null
)
```

## StatusMessage (detalles del error)

> **Disponible desde el SDK de Android v2.22.0**

Cada callback de resultado de pago e inscripción, y el `returnStatus` de los listeners de render, incluye un `StatusMessage?` junto al estado. Distingue un **rechazo del backend** de un **fallo interno del SDK** y te da un código sobre el cual actuar, en lugar de una cadena de estado plana.

```kotlin theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
package com.yuno.payments.features.payment.models

data class StatusMessage(
    val source: String,          // "backend" or "sdk"
    val code: String? = null,    // backend response_code, or an SDK error code
    val reason: String? = null,  // human-readable detail
    val raw: String? = null,     // redacted subset of the backend error body (backend only)
    val context: String? = null, // where the SDK failed (sdk only), e.g. "startPayment"
)
```

| Campo | `source = "backend"` | `source = "sdk"` |
| - | - | - |
| `code` | El `response_code` de la transacción (por ejemplo, `INSUFFICIENT_FUNDS`) o el `code` del error HTTP devuelto por Yuno. | Un código de error del SDK: `UNEXPECTED_ERROR`, `LOADER_TIMEOUT` o `PAYMENT_METHOD_NOT_SELECTED` (desde `2.25.0`). |
| `reason` | El `response_message` de la transacción, con su `reason` como alternativa; para errores HTTP, la primera entrada de `messages` del backend. | Una descripción breve del fallo. |
| `raw` | Subconjunto permitido y con límite de tamaño del cuerpo del error del backend: solo `code`, `message`, `messages`, `type` y `request_id`, con un máximo de 2048 caracteres; de lo contrario, `null`. Aun así puede reflejar datos que enviaste, por lo que no lo registres tal cual en los logs. | Siempre `null`. |
| `context` | Siempre `null`. | El paso del SDK que falló, por ejemplo `startPayment`, `continuePayment` o `enrollment`. |

Cuándo se completa:

| Resultado | `message` |
| - | - |
| `SUCCEEDED`, `PROCESSING`, `CANCELED_BY_USER` (pagos) / `CANCELED` (inscripción), incluso cuando el comprador abandona el flujo antes de obtener un resultado | Siempre `null`. |
| `INTERNAL_ERROR` | Siempre presente. `source = "sdk"` para fallos del SDK, de render o de red; `source = "backend"` cuando Yuno respondió con un error HTTP. |
| `REJECT`, `FAIL` (pagos) | Presente con `source = "backend"` solo cuando el backend devolvió un `response_code` para la transacción; `null` en caso contrario. |
| `REJECT`, `FAIL` (inscripción) | `null`: los rechazos de inscripción no incluyen un `response_code` del backend. |

```kotlin theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
callbackPaymentState = { state, subState, message ->
    when (state) {
        "REJECT", "FAIL" -> showDeclined(code = message?.code, reason = message?.reason)
        "INTERNAL_ERROR" -> when (message?.source) {
            "backend" -> reportBackendError(message.code, message.raw)
            else -> reportSdkError(message?.code, message?.context)
        }
        else -> { }
    }
}
```

### Integración con render

Si integras mediante la API de render, el mismo valor llega a tus listeners como el último parámetro de `returnStatus`:

```kotlin theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
interface YunoPaymentRenderListener {
    fun returnStatus(
        resultCode: Int,
        paymentStatus: String,
        paymentSubStatus: String? = null,
        message: StatusMessage? = null,
    )
    // showView, returnOneTimeToken, loadingListener unchanged
}

interface YunoEnrollmentRenderListener {
    fun returnStatus(resultCode: Int, paymentStatus: String, message: StatusMessage? = null)
    // showView, loadingListener unchanged
}
```

### Migración a 2.22.0

`StatusMessage` es un **cambio incompatible**: el SDK no incluye sobrecargas obsoletas de las firmas anteriores. Cuando actualices desde `2.21.x` o una versión anterior:

1. **Recompila tu app con el nuevo SDK.** Agregar el nuevo AAR a una app compilada con una versión anterior no es seguro: un listener de render compilado con la firma anterior de `returnStatus` se bloquea en tiempo de ejecución con `AbstractMethodError` en el primer resultado de error, sin ninguna advertencia en tiempo de compilación.
2. **Agrega el tercer parámetro a cada lambda de `callbackPaymentState`** (`startCheckout`, `startPayment`, `startPaymentLite`, `startPaymentSeamlessLite`, `continuePayment`, `continueCardPayment`): `{ state, subState -> }` pasa a ser `{ state, subState, message -> }`. Las lambdas de Kotlin deben coincidir en aridad, por lo que la forma anterior no compila.
3. **Agrega el segundo parámetro a cada lambda de `callbackEnrollmentState`** (`initEnrollment`, `startEnrollment`, `enrollmentStatus`, `setupEnrollmentInfo`): `{ state -> }` pasa a ser `{ state, message -> }`.
4. **Actualiza tus sobrescrituras de `returnStatus`** en `YunoPaymentRenderListener` y `YunoEnrollmentRenderListener` a las firmas anteriores.

Leer `message` es opcional: si ignoras el nuevo parámetro, tu lógica existente sigue funcionando. Notas de la versión: [Changelog de Android](https://docs.y.uno/changelog/android.md).

## Inscripción de métodos de pago

Puedes inscribir métodos de pago (almacenar tarjetas para uso futuro) durante el flujo de pago o mediante flujos de inscripción dedicados. Para los flujos de pago, habilita el guardado de tarjetas en `YunoConfig`. Además, configura `payment_method.vault_on_success` (o equivalente) al crear la sesión de checkout, donde sea compatible. Para la inscripción dedicada, consulta [Flujos de inscripción (Android)](https://docs.y.uno/es/docs/sdks/card-enrollment/android-enrollment.md).

## Parámetro `keepLoader`

> **Disponible desde el SDK de Android v2.13.0**

### Cómo funciona

El parámetro `keepLoader` te permite mantener el indicador de carga del SDK a lo largo de todo el flujo `startPayment` → `continuePayment`. Esto evita que el indicador parpadee entre los pasos.

De forma predeterminada, el SDK oculta su indicador de carga después de generar el token de un solo uso (OTT). Vuelve a mostrarlo cuando se llama a `continuePayment`. Con `keepLoader` habilitado, el indicador permanece visible de forma continua desde que el usuario envía el formulario de pago hasta que el pago se procesa por completo (o se oculta explícitamente).

```mermaid theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
sequenceDiagram
    participant Merchant
    participant SDK as Yuno SDK
    participant User as Loader Screen

    Merchant->>SDK: startPayment(keepLoader: true)
    SDK->>User: Show Loader
    SDK->>Merchant: callbackOTT(token)
    Note over User: Loader remains visible
    Merchant->>SDK: continuePayment()
    SDK->>User: Dismiss Loader
```

### Integración

#### Habilita en YunoConfig

```kotlin theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
Yuno.initialize(
    applicationContext = this,
    apiKey = "YOUR_PUBLIC_API_KEY",
    config = YunoConfig(
        keepLoader = true,
    ),
)
```

#### Gestiona el OTT y llama a `continuePayment`

Cuando `keepLoader` está habilitado, el callback del OTT se activa mientras el indicador de carga sigue visible. Crea tu pago en tu backend y luego llama a `continuePayment` como de costumbre:

```kotlin theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
activity.startCheckout(
    checkoutSession = checkoutSession,
    countryCode = countryCode,
    callbackOTT = { token ->
        // The loader is still visible at this point.
        // Create payment on your backend using the token,
        // then call continuePayment:
        activity.continuePayment(showPaymentStatus = true)
    },
    callbackPaymentState = { state, subState, message ->
        // Handle final payment state
    },
)
```

#### Gestiona los errores con `hideLoader`

Si falla la llamada a tu backend y no puedes continuar con `continuePayment`, llama a `hideLoader()`. Esto oculta el indicador de carga y finaliza el flujo de pago:

```kotlin theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
callbackOTT = { token ->
    try {
        val payment = createPaymentOnBackend(token)
        activity.continuePayment(showPaymentStatus = true)
    } catch (e: Exception) {
        // Dismiss the loader on failure
        activity.hideLoader()
    }
}
```

> [!WARNING]
>
> **Manejo de fallos**\
> Cuando `keepLoader` está activo y falla la creación del pago, **debes** llamar a `hideLoader()`. De lo contrario, el indicador de carga permanecerá en pantalla indefinidamente (hasta que se active el tiempo de espera integrado).

### Compatibilidad

* Funciona con los flujos de pago **Full** y **Lite** (`startPayment` y `startPaymentLite`).
* Compatible con tokens almacenados (vaulted).
* El indicador de carga respeta el tiempo de espera integrado del SDK. Si no se llama ni a `continuePayment` ni a `hideLoader`, el indicador se ocultará automáticamente después del período de espera.
* No aplica al flujo **Seamless** (`startPaymentSeamlessLite`). Este flujo no usa el patrón de dos pasos `startPayment` → `continuePayment`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.