> ## 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 dirección de envío en la hoja de Apple Pay usando el SDK de iOS o Web.

Disponible desde Yuno iOS 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 un selector de método de envío convierten la hoja de Apple Pay en un express checkout:

* **Desglose del pedido**: muestra subtotal, envío, impuestos y 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 Estándar, Express o Mismo día en la hoja, con actualización instantánea de precios.

Cada capacidad es opcional. Si no las usas, tu integración de Apple Pay funciona exactamente como antes.

## Requisitos

| Requisito | Valor |
| - | - |
| Yuno iOS SDK | 2.24.0 o posterior |
| Yuno Web SDK | 1.10.8 o posterior |
| Apple Pay | [Configurado](https://docs.y.uno/es/docs/wallets/apple-pay/apple-pay-sdk-integration.md) en tu aplicación y habilitado en tu cuenta de Yuno |
| Dirección de envío en la hoja | Se solicita automáticamente en cuanto la sesión tiene `shipping_methods` o tu aplicación registra el handler, en ambas plataformas. No necesitas habilitarla en el Checkout Builder. |

## Cómo funciona

1. Tu backend agrega `summary_items` y/o `shipping_methods` cuando crea la sesión de checkout.
2. Tu aplicación registra `onShippingAddressChanged`: en iOS, en el delegate que ya pasa al flujo de pago; en Web, en `externalButtons` cuando inicia el checkout.
3. En la hoja de Apple Pay, cambiar el método de envío actualiza el precio al instante sin llamar a tu aplicación. 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:

* Toda 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 como la línea del beneficiario (recomendamos el nombre de tu tienda).
* Todos los montos deben usar la moneda de la sesión. Una moneda diferente hace que el SDK ignore ese desglose o respuesta.

## Paso 1: muestra un 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 } }
  ]
}
```

La hoja ahora muestra el desglose con el total etiquetado como "ACME Inc.". No se necesita código en la aplicación.

* La última entrada se muestra como el total general y su etiqueta como la línea del beneficiario.
* Los descuentos pueden ser negativos, por ejemplo `-5.00`.
* Cuando también envías `shipping_methods` (Paso 2), la hoja se abre con el desglose del primer método y esta lista se ignora.
* Sin `summary_items` y sin `shipping_methods`, la hoja muestra una sola línea con el monto de la sesión.

## 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 puede actualizar el precio en cuanto el cliente cambia 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 },
    "delivery_estimate": { "from": "2026-10-12", "to": "2026-10-14" },
    "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 primer método viene preseleccionado y su desglose es con el que se abre la hoja.
* `label` es el nombre de la opción y `detail` su descripción. Apple Pay muestra el precio junto a la opción.
* Cambiar de método nunca llama a tu aplicación ni a tu backend. El total proviene de los `summary_items` de ese método. Un método sin desglose conserva los totales que ya están en la hoja.
* `delivery_estimate` es un par `from` y `to` de fechas `YYYY-MM-DD`. Se muestra como un rango de fechas junto a la opción en iOS 15 y posteriores, y en Web en los navegadores que admiten Apple Pay JS versión 12 (Safari 15 y posteriores). Un rango invertido o mal formado no se muestra.
* La hoja acepta hasta 100 métodos, 100 summary items y 100 ítems por método. Por encima de eso, el SDK de iOS abre la hoja sin métodos de envío, y el SDK Web no abre la hoja y reporta un error.

## Paso 3: reacciona a los cambios de 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] iOS
>
> Haz que el delegate que ya pasas al flujo de pago cumpla con `YunoShippingDelegate` e implementa `onShippingAddressChanged`. Funciona con todos los flujos que reciben un `YunoPaymentDelegate`: `startCheckout`, `startPaymentLite` y la lista de métodos de pago del modo Full.
>
> ```swift theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> import YunoSDK
>
> final class CheckoutDelegate: YunoShippingDelegate {
>
>     // ... your YunoPaymentDelegate implementation (checkoutSession, countryCode, yunoPaymentResult, ...)
>
>     func onShippingAddressChanged(
>         _ paymentMethodType: String,
>         shippingInfo: YunoShippingInfo
>     ) async -> YunoShippingUpdate? {
>         // paymentMethodType is "APPLE_PAY"
>         await myShippingService.quote(shippingInfo.shippingAddress) // a YunoShippingUpdate, or nil to keep the current values
>     }
> }
> ```
>
> Si no usas `async`, o integras desde Objective-C, implementa en su lugar la variante basada en completion que `YunoPaymentDelegate` declara como opcional:
>
> ```swift theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> func onShippingAddressChanged(
>     paymentMethodType: String,
>     shippingInfo: YunoShippingInfo,
>     completion: @escaping (YunoShippingUpdate?) -> Void
> ) {
>     myShippingService.quote(shippingInfo.shippingAddress) { quote in
>         completion(quote)
>     }
> }
> ```
>
> Implementa una de las dos. Cuando existen ambas, el SDK llama a la `async`.

> [tab] Web
>
> ```javascript theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> await yuno.startCheckout({
>   checkoutSession: session,
>   countryCode: 'US',
>   yunoCreatePayment: (oneTimeToken) => { /* create the payment on your server */ },
>   externalButtons: {
>     onShippingAddressChanged: async ({ paymentMethodType, shippingInfo }) => {
>       // paymentMethodType is "APPLE_PAY"
>       return await myShippingService.quote(shippingInfo.shippingAddress) // a ShippingUpdate, or null to keep the current values
>     },
>   },
> })
> ```
>
> La misma opción `externalButtons.onShippingAddressChanged` existe en `startSeamlessCheckout`. El handler se comparte con Google Pay en Web: cuando el cliente paga con Google Pay se llama con `paymentMethodType: "GOOGLE_PAY"`, así que ramifica según ese valor si cotizas de forma distinta por billetera.

### Lo que recibes: ShippingInfo

Antes de la autorización, Apple Pay 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?` | `"Cupertino"` |
| `shippingAddress.state` | `String?` | `"CA"` |
| `shippingAddress.postalCode` | `String?` | `"95014"` (puede estar abreviado en algunos países) |
| `shippingAddress.countryCode` | `String?` | `"US"` |

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

### Lo que devuelves: ShippingUpdate

Devuelve cualquier combinación de estos, o `nil` (`null` en Web) para dejar la hoja como está.

> [tab] iOS
>
> ```swift theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> // A) New totals for this address
> YunoShippingUpdate(
>     summaryItems: [
>         YunoSummaryItem(id: "subtotal", label: "Subtotal", amount: YunoShippingAmount(currency: "USD", value: 100.00)),
>         YunoSummaryItem(id: "tax", label: "Tax", amount: YunoShippingAmount(currency: "USD", value: 10.00)),
>         YunoSummaryItem(id: "total", label: "ACME Inc.", amount: YunoShippingAmount(currency: "USD", value: 110.00)) // must be last
>     ]
> )
> ```
>
> ```swift theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> // B) New shipping methods for this address
> YunoShippingUpdate(
>     shippingMethods: [
>         YunoShippingMethod(
>             id: "same-day", label: "Same-day delivery", detail: "Today before 9pm",
>             amount: YunoShippingAmount(currency: "USD", value: 15.00),
>             deliveryEstimate: YunoShippingDeliveryEstimate(from: "2026-10-10", to: "2026-10-10"),
>             summaryItems: [
>                 YunoSummaryItem(id: "subtotal", label: "Subtotal", amount: YunoShippingAmount(currency: "USD", value: 100.00)),
>                 YunoSummaryItem(id: "shipping", label: "Shipping", amount: YunoShippingAmount(currency: "USD", value: 15.00)),
>                 YunoSummaryItem(id: "total", label: "ACME Inc.", amount: YunoShippingAmount(currency: "USD", value: 115.00))
>             ]
>         )
>     ]
> )
> ```
>
> ```swift theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> // C) An address you can't serve
> YunoShippingUpdate(
>     errors: [
>         YunoShippingError(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 },
>       deliveryEstimate: { from: '2026-10-10', to: '2026-10-10' },
>       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é sucede |
| - | - |
| Devuelves `nil` (o nada en Web) | Los valores actuales se mantienen. |
| Respondes tarde | El SDK no establece un plazo propio: la hoja permanece abierta mientras respondes. Si el límite de tiempo de Apple se cumple primero, Apple cierra la hoja y el SDK reporta `CANCELED_BY_USER`. Responde lo más rápido que puedas. |
| Una moneda difiere de la de la sesión, o un monto no es un número | Toda la respuesta se ignora. |
| Envías `summaryItems` | La lista debe terminar con el total general, que se convierte en el total de la hoja. Se aplica al método seleccionado actualmente; al cambiar a otro método se restablece el desglose propio de ese método. |
| Envías `shippingMethods` | Reemplazan las opciones y la primera queda preseleccionada. Incluye `summaryItems` en cada método; de lo contrario, el total no cambia cuando el cliente cambia de método. |
| Envías `errors` | Apple Pay muestra el mensaje en la hoja y bloquea el pago hasta que el cliente elija otra dirección. `CITY_NOT_SUPPORTED`, `STATE_NOT_SUPPORTED`, `COUNTRY_NOT_SUPPORTED` y `POSTAL_CODE_INVALID` señalan ese campo de la dirección; en Web, `ADDRESS_NOT_SUPPORTED` marca toda la dirección como no atendible. Cualquier otro código se muestra como un error genérico de "no se puede enviar a esta dirección". |
| Más de 100 entradas | Toda la respuesta se ignora. |
| Tu handler lanza una excepción (o rechaza en Web) | Los valores actuales se mantienen. |
| La hoja se abre | Apple Pay llama a tu handler de inmediato con la dirección predeterminada del cliente. 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 `nil` para conservarlos. |
| El cliente cambia la dirección otra vez mientras todavía respondes | La llamada anterior se cancela y solo se aplica la respuesta a la dirección más reciente. |

> [!NOTE]
>
> A diferencia de Google Pay, un error en la hoja de Apple Pay sí bloquea el pago: el cliente tiene que elegir otra dirección antes de pagar. Aun así, valida la dirección en tu servidor cuando crees el pago.

## 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 `yunoCreatePayment` incluye un objeto `shipping` con el método seleccionado y la dirección completa:

```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": "1 Apple Park Way",
    "address_line_2": "",
    "city": "Cupertino",
    "state": "CA",
    "zip_code": "95014",
    "country": "US"
  }
}
```

* `method` es el seleccionado en la hoja, o el primero si el cliente no lo cambió.
* Los `summary_items` no se envían de vuelta.
* El objeto se incluye siempre que la hoja haya recopilado un método de envío o una dirección, con o sin handler. Los pagos sin ninguno de los dos no incluyen `shipping`.

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

## Qué sucede en cada caso

| Handler implementado | `summary_items` en la sesión | `shipping_methods` en la sesión | Hoja de Apple Pay |
| - | - | - | - |
| No | No | No | Igual que antes (un solo total) |
| No | Sí | No | Desglose, sin actualizaciones de dirección |
| No | Cualquiera | Sí | Selector con cambios instantáneos de método. La hoja solicita la dirección, pero tu aplicación no recibe llamadas |
| Sí | No | No | Actualizaciones de dirección; los totales cambian con tus respuestas. Sin selector a menos que devuelvas métodos |
| Sí | Sí | No | Primero el desglose; tus respuestas pueden actualizarlo |
| Sí | Cualquiera | Sí | Experiencia completa: selector, cambios instantáneos de método y actualizaciones de dirección |

## Es bueno saber

* En iOS, Apple Pay no es compatible con el iOS Simulator. Prueba en un dispositivo físico. En Web, prueba en Safari en un dispositivo con Apple Pay configurado.
* Apple Pay censura la dirección hasta que se autoriza el pago, por lo que tu handler nunca ve las líneas de calle.
* 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, emails ni datos de pago.

## Solución de problemas

| Síntoma | Causa probable |
| - | - |
| El selector no aparece | La sesión no tiene `shipping_methods` válidos, una moneda difiere de la de la sesión, o la sesión supera 100 métodos, summary items o ítems por método (en Web, en ese caso la hoja no se abre en absoluto). |
| El desglose no aparece | `summary_items` no es válido (sin total, etiqueta vacía, monedas mezcladas). |
| La hoja no solicita una dirección de envío | La sesión no tiene `shipping_methods` y tu aplicación no implementa el handler. Agrega cualquiera de los dos, o habilita la dirección de envío como campo obligatorio en el Checkout Builder. |
| Mi handler nunca se llama | En iOS, tu delegate no cumple con `YunoShippingDelegate` y tampoco implementa la variante basada en completion. En Web, `externalButtons.onShippingAddressChanged` no se pasó a `startCheckout` ni a `startSeamlessCheckout`. |
| Mis métodos reemplazaron los de la sesión cuando se abrió la hoja | Apple Pay llama a tu handler cuando se abre la hoja y tu respuesta se aplica. Devuelve `nil` 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. |
| La hoja conserva los totales anteriores después de mi respuesta | Una moneda difiere de la de la sesión, la respuesta tiene más de 100 entradas, o el cliente cambió la dirección otra vez antes de que respondieras. |
| Las fechas de entrega no se muestran | El dispositivo usa iOS 14 o anterior, el navegador no admite Apple Pay JS versión 12, o `from` es posterior a `to`. |
| La hoja se cerró sola y recibí `CANCELED_BY_USER` | Tu handler tardó más que el límite de tiempo de Apple. Responde más rápido, o devuelve `nil` y cotiza en tu servidor cuando crees el pago. |

## Documentación relacionada

* [Configuración y pagos de un solo uso](https://docs.y.uno/es/docs/wallets/apple-pay/apple-pay-sdk-integration.md)
* [Express checkout de Google Pay en Android](https://docs.y.uno/es/docs/wallets/google-pay/sdk-integration/express-checkout.md)
* [Fast Checkout Shipping](https://docs.y.uno/es/docs/payment-features/fast-checkout-shipping.md). Los mismos campos de sesión y el nodo `shipping` en billeteras que eligen la dirección dentro del widget.
* [Changelog del SDK de iOS](https://docs.y.uno/changelog/ios.md) y [Changelog del SDK Web](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.