> ## 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.

# Express checkout

> Muestra el desglose del pedido, ofrece métodos de envío y reacciona a los cambios de la dirección de envío en la hoja de Google Pay con el SDK de Android o Web.

Disponible desde Yuno Android SDK 2.24.0 y Yuno Web SDK 1.10.8.

El desglose del pedido, las actualizaciones de la dirección de envío y el selector de método de envío convierten la hoja de Google Pay en un express checkout:

* **Desglose del pedido**: muestra el subtotal, el envío, los impuestos y los descuentos en lugar de un solo total.
* **Actualizaciones de la dirección de envío**: recalcula el pedido cuando el cliente elige o cambia su dirección de envío, sin salir de la hoja.
* **Selector de método de envío**: permite que el cliente elija Standard, Express o Same-day en la hoja, con actualizaciones de precio instantáneas.

Cada capacidad es opcional. Si no las usas, tu integración de Google Pay funciona exactamente igual que antes.

## Requisitos

| Requisito | Valor |
| - | - |
| Yuno Android SDK | 2.24.0 o posterior, con `minSdkVersion` 23 (Android 6.0) o superior. Sin cambios en el manifest. |
| Yuno Web SDK | 1.10.8 o posterior |
| Google Pay | Habilitado en tu cuenta de Yuno |

> [!WARNING]
>
> **En Android, actualizar a 2.24.0 es un cambio incompatible.**
>
> * Establece `minSdkVersion` en 23 o superior. Con 21 o 22 la compilación falla en el paso de combinación del manifest.
> * Si tu app fija `com.google.android.gms:play-services-wallet` en una versión anterior a `20.0.0`, quita esa fijación o usa `20.0.0` o superior.
> * Si llamas a `startCheckout`, `startPayment`, `startPaymentLite`, `startPaymentSeamlessLite` o `continuePayment` pasando todos los argumentos por posición, actualiza la llamada: se agregó un nuevo parámetro opcional antes del último callback. Las llamadas que usan argumentos con nombre o una lambda final no necesitan cambios.
>
> Consulta el [changelog del SDK de Android](https://docs.y.uno/changelog/android.md#v2-24-0) para más detalles.

En Web no hay cambios incompatibles ni cambios en la página: el SDK carga y configura Google Pay por ti. Si cargas una versión fija del SDK (por ejemplo, con un hash de integridad), asegúrate de que sea 1.10.8 o posterior.

## Cómo funciona

1. Tu backend agrega `summary_items` y/o `shipping_methods` cuando crea la sesión de checkout.
2. Tu app registra `onShippingAddressChanged` cuando inicia el flujo de pago.
3. En la hoja de Google Pay, cambiar el método de envío actualiza el precio al instante sin llamar a tu app. Elegir o cambiar la dirección de envío llama a tu handler, para que puedas devolver nuevos totales, nuevos métodos o un error.
4. Después de que el cliente autoriza, el token de un solo uso incluye un objeto `shipping` con el método seleccionado y la dirección completa.

Dos reglas aplican en todos los casos:

* Cada lista `summary_items` debe terminar con el total general. Su `amount` es el total que se muestra en la hoja, y su `label` se muestra junto a él (recomendamos el nombre de tu tienda).
* Todos los montos deben usar la moneda de la sesión. Si la moneda es distinta, el SDK ignora ese desglose o esa respuesta.

## Paso 1: muestra el desglose del pedido (solo backend)

Agrega `summary_items` cuando [crees la sesión de checkout](https://docs.y.uno/es/reference/checkout-sessions/create-checkout-session.md):

```json theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "amount": { "currency": "USD", "value": 108.00 },
  "customer_id": "customer-uuid",
  "merchant_order_id": "order-123",
  "country": "US",
  "summary_items": [
    { "id": "subtotal", "label": "Subtotal", "amount": { "currency": "USD", "value": 100.00 } },
    { "id": "tax", "label": "Tax", "amount": { "currency": "USD", "value": 8.00 } },
    { "id": "total", "label": "ACME Inc.", "amount": { "currency": "USD", "value": 108.00 } }
  ]
}
```

Ahora la hoja muestra un desglose expandible con el total etiquetado como "ACME Inc.". No se necesita código en la app.

* Los ids `subtotal`, `shipping`, `tax` y `discount` usan los tipos de línea nativos de Google. Cualquier otro id se muestra como una línea normal. El cliente solo ve tus etiquetas.
* La última entrada debe ser el total general y debe coincidir con el monto de la sesión (tolerancia de 0.001 en Android, 0.01 en Web). Si no coincide, la hoja muestra solo el total.
* Los descuentos pueden ser negativos, por ejemplo `-5.00`.
* Envía al menos dos entradas: una línea más el total general. Si la lista no es válida (menos de dos entradas, falta una etiqueta o un monto, monedas mezcladas, sin total), la hoja muestra solo el total. Nada se rompe y el cliente no ve ningún error.
* Sin desglose, el Web SDK etiqueta el monto como "Total" en el idioma del checkout (SDK 1.11.17 o posterior).
* Cuando también envías `shipping_methods` (Paso 2) y registras el handler, la hoja muestra el desglose del primer método y esta lista se ignora.

## Paso 2: ofrece métodos de envío en la hoja

Agrega `shipping_methods` a la sesión de checkout. Cada método tiene sus propios `summary_items`, de modo que la hoja pueda actualizar el precio apenas el cliente cambie de método:

```json theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
"shipping_methods": [
  {
    "id": "standard",
    "label": "Standard shipping",
    "detail": "Arrives in 3-5 business days",
    "amount": { "currency": "USD", "value": 5.00 },
    "summary_items": [
      { "id": "subtotal", "label": "Subtotal", "amount": { "currency": "USD", "value": 100.00 } },
      { "id": "shipping", "label": "Shipping", "amount": { "currency": "USD", "value": 5.00 } },
      { "id": "total", "label": "ACME Inc.", "amount": { "currency": "USD", "value": 105.00 } }
    ]
  },
  {
    "id": "express",
    "label": "Express shipping",
    "detail": "Arrives in 1-2 business days",
    "amount": { "currency": "USD", "value": 12.00 },
    "summary_items": [
      { "id": "subtotal", "label": "Subtotal", "amount": { "currency": "USD", "value": 100.00 } },
      { "id": "shipping", "label": "Shipping", "amount": { "currency": "USD", "value": 12.00 } },
      { "id": "total", "label": "ACME Inc.", "amount": { "currency": "USD", "value": 112.00 } }
    ]
  }
]
```

El selector necesita el handler del Paso 3. Sin él, la hoja ignora los métodos y funciona como antes.

* Cada método necesita un id único. Si dos métodos comparten un id, el selector no se muestra.
* El primer método viene preseleccionado.
* El precio se muestra en el nombre de la opción, por ejemplo "\$5.00: Standard shipping". `detail` se muestra como la descripción.
* Cambiar de método nunca llama a tu app ni a tu backend. El total proviene de los `summary_items` de ese método.
* Los `summary_items` de cada método deben terminar con el total de ese método, que puede ser distinto del monto de la sesión. Envía al menos una línea más el total. Un método que solo tiene el total no muestra desglose y usa la etiqueta de total predeterminada de Google.
* Si algún método no es válido, el selector no se muestra.
* `delivery_estimate` (`{ "from": "YYYY-MM-DD", "to": "YYYY-MM-DD" }`) se acepta, pero Google Pay no lo muestra ni en Android ni en Web.

## Paso 3: reacciona a los cambios de la dirección de envío

Registra `onShippingAddressChanged` cuando inicies el flujo. Tu handler recibe la dirección censurada y responde con nuevos totales, nuevos métodos, un error o nada para dejar la hoja como está.

> [tab] Android
>
> ```kotlin theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> import com.yuno.sdk.payments.shipping.*
>
> activity.startCheckout(
>     checkoutSession = session,
>     countryCode = "US",
>     callbackOTT = { token -> /* create the payment on your server */ },
>     onShippingAddressChanged = { paymentMethodType, shippingInfo, complete ->
>         // paymentMethodType is "GOOGLE_PAY"
>         myShippingService.quoteAsync(shippingInfo.shippingAddress) { quote ->
>             complete(quote) // a ShippingUpdate, or null to keep the current values
>         }
>     },
> )
> ```
>
> El mismo parámetro opcional existe en `startPayment`, `startPaymentLite`, `startPaymentSeamlessLite` y `continuePayment`. Regístralo cada vez que inicies un flujo.

> [tab] Web
>
> Registra `onShippingAddressChanged` en la raíz de `externalButtons` cuando inicies el checkout:
>
> ```javascript theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> const yuno = await Yuno.initialize(PUBLIC_API_KEY)
>
> await yuno.startCheckout({
>   checkoutSession: CHECKOUT_SESSION,
>   elementSelector: '#root',
>   countryCode: 'US',
>   language: 'en',
>   externalButtons: {
>     onShippingAddressChanged: async ({ paymentMethodType, shippingInfo }) => {
>       // paymentMethodType is "GOOGLE_PAY"
>       const quote = await myShippingService.quote(shippingInfo.shippingAddress)
>       return quote // a ShippingUpdate, or null to keep the current values
>     },
>   },
>   async createPayment(oneTimeToken) {
>     // create the payment on your server
>   },
> })
>
> await yuno.mountCheckout()
> ```
>
> * El handler debe ser una función `async` o devolver una Promise. Si devuelve un objeto simple, el SDK ignora la respuesta.
> * Funciona en todos los flujos que muestran el botón de Google Pay (`mountCheckout`, `mountExternalButtons` y `mountSeamlessExternalButtons`), siempre que lo pases a `startCheckout` o `startSeamlessCheckout`.
> * Regístralo antes de que se renderice el botón de Google Pay. El SDK lo verifica una sola vez, cuando aparece el botón.
> * El handler se comparte con Apple Pay: cuando el cliente paga con Apple Pay se llama con `paymentMethodType: "APPLE_PAY"`, así que ramifica según ese valor si cotizas de forma distinta por wallet.

### Lo que recibes: ShippingInfo

Antes de la autorización, Google comparte solo una parte de la dirección, que es suficiente para cotizar el envío y los impuestos:

| Campo | Tipo | Ejemplo |
| - | - | - |
| `shippingAddress.city` | `String?` | `"Mountain View"` |
| `shippingAddress.state` | `String?` | `"CA"` |
| `shippingAddress.postalCode` | `String?` | `"94043"` (puede estar abreviado en algunos países) |
| `shippingAddress.countryCode` | `String?` | `"US"` |

Cualquier campo puede faltar: `null` en Android, ausente en Web. La dirección completa llega en el token de un solo uso (Paso 4).

### Lo que devuelves: ShippingUpdate

Responde con cualquier combinación de estos elementos, o con `null` para dejar la hoja como está. En Android llama a `complete(...)`; en Web devuelve el valor desde el handler.

> [tab] Android
>
> ```kotlin theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> // A) New totals for this address
> complete(ShippingUpdate(
>     summaryItems = listOf(
>         SummaryItem("subtotal", "Subtotal", SummaryAmount("USD", 100.00)),
>         SummaryItem("tax", "Tax", SummaryAmount("USD", 10.00)),
>         SummaryItem("total", "ACME Inc.", SummaryAmount("USD", 110.00)), // must be last
>     ),
> ))
> ```
>
> ```kotlin theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> // B) New shipping methods for this address
> complete(ShippingUpdate(
>     shippingMethods = listOf(
>         ShippingMethod(
>             id = "same-day", label = "Same-day delivery", detail = "Today before 9pm",
>             amount = SummaryAmount("USD", 15.00),
>             summaryItems = listOf(
>                 SummaryItem("subtotal", "Subtotal", SummaryAmount("USD", 100.00)),
>                 SummaryItem("shipping", "Shipping", SummaryAmount("USD", 15.00)),
>                 SummaryItem("total", "ACME Inc.", SummaryAmount("USD", 115.00)),
>             ),
>         ),
>     ),
> ))
> ```
>
> ```kotlin theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> // C) An address you can't serve
> complete(ShippingUpdate(
>     errors = listOf(ShippingError(
>         code = "CITY_NOT_SUPPORTED",
>         message = "We don't ship to this city yet", // shown to the customer
>     )),
> ))
> ```

> [tab] Web
>
> ```javascript theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> // A) New totals for this address
> return {
>   summaryItems: [
>     { id: 'subtotal', label: 'Subtotal', amount: { currency: 'USD', value: 100.00 } },
>     { id: 'tax', label: 'Tax', amount: { currency: 'USD', value: 10.00 } },
>     { id: 'total', label: 'ACME Inc.', amount: { currency: 'USD', value: 110.00 } }, // must be last
>   ],
> }
> ```
>
> ```javascript theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> // B) New shipping methods for this address
> return {
>   shippingMethods: [
>     {
>       id: 'same-day', label: 'Same-day delivery', detail: 'Today before 9pm',
>       amount: { currency: 'USD', value: 15.00 },
>       summaryItems: [
>         { id: 'subtotal', label: 'Subtotal', amount: { currency: 'USD', value: 100.00 } },
>         { id: 'shipping', label: 'Shipping', amount: { currency: 'USD', value: 15.00 } },
>         { id: 'total', label: 'ACME Inc.', amount: { currency: 'USD', value: 115.00 } },
>       ],
>     },
>   ],
> }
> ```
>
> ```javascript theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> // C) An address you can't serve
> return {
>   errors: [
>     { code: 'CITY_NOT_SUPPORTED', message: "We don't ship to this city yet" }, // shown to the customer
>   ],
> }
> ```

### Reglas

| Situación | Qué ocurre |
| - | - |
| Devuelves `null` (o nada en Web) | Se mantienen los valores actuales. |
| Respondes tarde | Responde lo más rápido que puedas. El SDK no impone un límite de tiempo propio, pero Google sí (alrededor de 30 a 45 segundos en Web). Pasado ese tiempo, la hoja muestra un aviso de tiempo agotado y mantiene los valores actuales. En Android solo cuenta el primer `complete(...)`. |
| Una moneda difiere de la de la sesión | Se ignora toda la respuesta, incluidos los errores. |
| Envías `summaryItems` | La lista debe terminar con el total general, que se convierte en el total de la hoja. Puede ser distinto del monto de la sesión. Envía siempre una etiqueta. |
| Envías `shippingMethods` | Reemplazan las opciones y la primera viene preseleccionada. Su desglose define el total, y cualquier `summaryItems` de nivel superior en la misma respuesta se ignora. Incluye `summaryItems` en cada método; de lo contrario, el total no cambia cuando el cliente cambia de método. Solo se muestran si la sesión ya tenía `shipping_methods` válidos; de lo contrario, se descartan y tus `summaryItems` y `errors` se siguen aplicando. |
| Un método no es válido o dos métodos comparten un id | En Android se ignora toda la respuesta. En Web se ignoran los métodos y los totales no cambian, pero un error en la misma respuesta se sigue mostrando. |
| Envías `errors` | Google muestra el primer error en la hoja. Estos códigos apuntan al campo de la dirección: `CITY_NOT_SUPPORTED`, `STATE_NOT_SUPPORTED`, `COUNTRY_NOT_SUPPORTED`, `POSTAL_CODE_INVALID`, `ADDRESS_NOT_SUPPORTED`. Cualquier otro código se muestra como un error genérico. Si la misma respuesta también incluye totales o métodos, Google muestra el error y los aplica. |
| Tu handler lanza una excepción (o es rechazado en Web) | Se mantienen los valores actuales. La hoja y tu app no se bloquean. |
| Se abre la hoja | Google normalmente llama a tu handler de inmediato con la dirección predeterminada. Haz que tu handler sea seguro de llamar más de una vez y no dependas de esa primera llamada. Si devuelves métodos en esa llamada, reemplazan los de la sesión; devuelve `null` para conservarlos. |

Para cambiar los precios mientras se muestra el selector, devuelve la lista completa de `shippingMethods`, cada método con sus propios `summaryItems`. Si devuelves solo `summaryItems`, el total cambia, pero la próxima vez que el cliente cambie de método la hoja vuelve al desglose original de ese método.

> [!WARNING]
>
> Un error en la hoja no bloquea el pago. El cliente aún puede pagar, y el token lleva la dirección que rechazaste. Valida siempre la dirección en tu servidor cuando crees el pago. Si una venta no debe realizarse, no devuelvas ningún método de envío disponible para esa dirección.

## Paso 4: lee el resultado en el token de un solo uso

Después de que el cliente autoriza, el token de un solo uso que recibes en `callbackOTT` (Android) o `createPayment` (Web) incluye un objeto `shipping` con la dirección completa y el método seleccionado:

```json theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
"shipping": {
  "method": {
    "id": "express",
    "label": "Express shipping",
    "amount": { "currency": "USD", "value": 12.00 }
  },
  "address": {
    "address_line_1": "1600 Amphitheatre Parkway",
    "address_line_2": "",
    "city": "Mountain View",
    "state": "CA",
    "zip_code": "94043",
    "country": "US"
  }
}
```

* `method` es el seleccionado en la hoja, o el primero si el cliente no lo cambió. Su etiqueta es la que enviaste, sin el precio.
* Los campos vacíos de la dirección llegan como cadenas vacías en Android y se omiten en Web.
* Los `summary_items` no se devuelven.
* Si no registras un handler, el token no incluye `shipping`.

Usa este objeto en tu servidor para cobrar el monto final, validar la dirección y enviar el pedido.

## Qué ocurre en cada caso

| Handler registrado | `summary_items` en la sesión | `shipping_methods` en la sesión | Hoja de Google Pay |
| - | - | - | - |
| No | No | No | Igual que antes (un solo total) |
| No | Sí | – | Desglose, sin actualizaciones de dirección |
| No | – | Sí | Los métodos se ignoran sin el handler. Un `summary_items` válido se sigue mostrando |
| Sí | No | No | Actualizaciones de dirección; los totales cambian con tus respuestas. Sin selector |
| Sí | Sí | No | Primero el desglose; tus respuestas pueden actualizarlo |
| Sí | – | Sí | Experiencia completa: selector, cambios de método instantáneos y actualizaciones de dirección |

## Buenas prácticas

* Las direcciones pertenecen a la cuenta de Google del cliente. En el entorno TEST de Google Pay solo verás las direcciones de prueba de Google; no puedes agregar las tuyas.
* La hoja solicita una dirección de envío apenas se registra el handler. Sin un handler, solo la solicita cuando la dirección de envío está habilitada como campo obligatorio en el Checkout Builder.
* El método seleccionado sigue seleccionado cuando el cliente cambia la dirección, a menos que devuelvas nuevos métodos.
* **Privacidad:** el SDK nunca registra direcciones, correos electrónicos ni datos de pago.
* Google Pay Pix (Brasil) no se ve afectado.

## Solución de problemas

| Síntoma | Causa probable |
| - | - |
| La compilación falla en la combinación del manifest después de actualizar (Android) | Tu `minSdkVersion` es inferior a 23. |
| El selector no aparece | El handler no está registrado en este inicio de flujo (en Web, no estaba registrado cuando se renderizó el botón), dos métodos comparten un id, un método no es válido (cada uno necesita id, label, amount y `summary_items` que terminen con el total), o una moneda difiere de la de la sesión. |
| El desglose no aparece | `summary_items` no es válido (sin total, etiqueta vacía, monedas mezcladas) o el total difiere del monto de la sesión. |
| Mi handler nunca se llama | En Web, se agregó después de que se renderizó el botón, o no se pasó `externalButtons` a `startCheckout` o `startSeamlessCheckout`. Cambiar el método de envío nunca lo llama; cambia la dirección para probarlo. |
| Mi handler se ejecuta pero la hoja no cambia | En Web, el handler devuelve un objeto simple en lugar de una Promise; hazlo `async`. |
| Los métodos que devuelve mi handler no aparecen, pero los totales sí | La sesión no tenía `shipping_methods` válidos, así que no hay un selector que actualizar. Envía al menos un método válido en la sesión. |
| Mis métodos reemplazaron los de la sesión cuando se abrió la hoja | Google llama a tu handler cuando se abre la hoja y se aplica tu respuesta. Devuelve `null` en esa llamada para conservar los métodos de la sesión. |
| Cambiar de método no cambia el total | Los métodos no tienen `summaryItems`. Envía un desglose para cada método. |
| Un método muestra el total pero no el desglose | Sus `summary_items` solo tienen el total. Agrega al menos una línea. |
| Mi nuevo total vuelve al anterior cuando el cliente cambia de método | Devolviste solo `summaryItems` mientras se mostraba el selector. Devuelve la lista completa de `shippingMethods`. |
| Un cliente pagó con una dirección que rechacé | Los errores en la hoja no bloquean el pago. Valida la dirección en tu servidor cuando crees el pago. |
| La hoja mantiene los totales anteriores después de mi respuesta | Tu respuesta llegó después del límite de tiempo de Google, se llamó a `complete(...)` dos veces (Android), o una moneda difiere de la de la sesión. |
| Las fechas de entrega no se muestran | Google Pay no muestra `delivery_estimate`. |

## Documentación relacionada

* [Resumen de Google Pay](https://docs.y.uno/docs/google-pay)
* [Configuración y pagos únicos](https://docs.y.uno/es/docs/wallets/google-pay/google-pay-sdk-integration.md)
* [Integración del SDK de Apple Pay](https://docs.y.uno/es/docs/wallets/apple-pay/apple-pay-sdk-integration.md)
* [Referencia del Web SDK: `externalButtons`](https://docs.y.uno/docs/sdks/resources/references/web#express-button-styling-externalbuttons)
* [Changelog del SDK de Android](https://docs.y.uno/changelog/android.md#v2-24-0) y [changelog del Web SDK](https://docs.y.uno/changelog/web.md#v1-10-8)


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