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

# Experiencia mejorada de billeteras

> Habilita una experiencia directa de billeteras en el checkout de VTEX y desbloquea las cuotas de Apple Pay, Google Pay y Samsung Pay.

La experiencia mejorada de billeteras es un complemento opcional para las tiendas que ya usan el plugin de Yuno para VTEX. Mejora la experiencia de checkout de los compradores al eliminar una pantalla intermedia entre el checkout de VTEX y la hoja nativa de la billetera del dispositivo, que se sabe que reduce la conversión en los pagos con billeteras.

![Experiencia predeterminada de billeteras](https://mintcdn.com/yuno-3979e326/z8Jixp_IwgkBlbdW/images/plugins/vtex/image-20260422-170119.png?fit=max\&auto=format\&n=z8Jixp_IwgkBlbdW\&q=85\&s=32c0b3a72e19dd8dcf254d05610885f1)

Experiencia predeterminada (con pantalla intermedia)

![Experiencia mejorada de billeteras](https://mintcdn.com/yuno-3979e326/z8Jixp_IwgkBlbdW/images/plugins/vtex/image-20260422-170132.png?fit=max\&auto=format\&n=z8Jixp_IwgkBlbdW\&q=85\&s=78db6548835bd4c98618e7596722dd89)

Experiencia mejorada (hoja nativa directa)

## Qué es

De forma predeterminada, cuando un comprador selecciona un pago con billetera (Apple Pay, Google Pay o Samsung Pay), la Yuno Payment App abre una pantalla intermedia dentro del checkout de VTEX antes de que aparezca la hoja nativa de confirmación del dispositivo (Face ID, fingerprint o PIN).

La **experiencia mejorada** elimina esa pantalla intermedia: los botones de las billeteras aparecen **directamente dentro del paso de pago del checkout de VTEX**, y al tocar un botón se abre de inmediato la hoja nativa del dispositivo.

Esta integración también desbloquea **cuotas** opcionales **para Apple Pay, Google Pay y Samsung Pay**.

## Cómo funciona

Cuando un comprador llega al checkout, el Yuno SDK prepara una sesión de pago de forma silenciosa en segundo plano. Cuando llega al paso de pago, los botones de las billeteras aparecen al instante.

* **Confirmación rápida**: al tocar un botón, se abre de inmediato la hoja nativa de la billetera.
* **Recálculo automático**: si el comprador cambia su carrito (agrega un artículo, aplica un cupón, cambia el envío), el SDK recalcula la sesión automáticamente.
* **Manejo de errores**: si un pago falla, el comprador puede intentarlo de nuevo sin volver a cargar la página.

***

## Guía de integración

Configurar la experiencia mejorada implica agregar un pequeño fragmento de JavaScript al checkout de VTEX y encontrar los valores con los que completarlo.

**1. Agrega el fragmento al checkout de VTEX**

El fragmento se agrega al archivo `checkout6-custom.js` de tu tienda desde el VTEX dashboard.

1. En el **VTEX dashboard**, busca **Checkout** en la barra superior.

![Configuración de Checkout de VTEX](https://mintcdn.com/yuno-3979e326/z8Jixp_IwgkBlbdW/images/plugins/vtex/vtex-checkout-snippet-1.png?fit=max\&auto=format\&n=z8Jixp_IwgkBlbdW\&q=85\&s=1c91cd38a8d5e044c3e3260e86e02541)

2. Selecciona el sitio web que usa tu tienda (normalmente **Default**).

![Seleccionar sitio web](https://mintcdn.com/yuno-3979e326/z8Jixp_IwgkBlbdW/images/plugins/vtex/vtex-checkout-snippet-2.png?fit=max\&auto=format\&n=z8Jixp_IwgkBlbdW\&q=85\&s=3b5d4da3eb2890fc2b4beb9665f90808)

3. Abre la pestaña **Code** y selecciona `checkout6-custom.js` en la lista de archivos de la derecha.

![Abrir checkout6-custom.js](https://mintcdn.com/yuno-3979e326/z8Jixp_IwgkBlbdW/images/plugins/vtex/vtex-checkout-snippet-3.png?fit=max\&auto=format\&n=z8Jixp_IwgkBlbdW\&q=85\&s=5f0c09f4c74f06d5a106db79204ee3af)

4. Agrega el siguiente fragmento al final del archivo y luego haz clic en **Save**.

![Guardar el fragmento](https://mintcdn.com/yuno-3979e326/z8Jixp_IwgkBlbdW/images/plugins/vtex/vtex-checkout-snippet-4.png?fit=max\&auto=format\&n=z8Jixp_IwgkBlbdW\&q=85\&s=5eafbaa0f7d8528278e59ab45b11076c)

```javascript theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
(function () {
  window.addEventListener('yuno-sdk-vtex-io-ready', function (event) {
    var YunoVTEXIO = event.detail.YunoVTEXIO;
    YunoVTEXIO.initialConfiguration({
      paymentMethods: ['Apple Pay', 'Google Pay', 'Samsung Pay'],
      affiliationName: 'YOUR_AFFILIATION_NAME'
    });
  });

  var script = document.createElement('script');
  script.src = 'https://sdk-web-vtex-io.y.uno/v1/main.js';
  document.head.appendChild(script);
})();
```

> [!NOTE]
>
> Reemplaza `YOUR_AFFILIATION_NAME` por el nombre de afiliación de la configuración de tu proveedor de Yuno. En `paymentMethods`, enumera las billeteras que quieres habilitar: `'Apple Pay'`, `'Google Pay'`, `'Samsung Pay'` o cualquier combinación.

**2. Encuentra el nombre de afiliación**

El valor `affiliationName` es el mismo que definiste al configurar Yuno como proveedor de pago.

1. En la barra de búsqueda del **VTEX dashboard**, escribe `providers` y selecciona el resultado **Providers**.

![Providers de VTEX](https://mintcdn.com/yuno-3979e326/z8Jixp_IwgkBlbdW/images/plugins/vtex/vtex-checkout-affiliation-1.png?fit=max\&auto=format\&n=z8Jixp_IwgkBlbdW\&q=85\&s=349fbce5142242452997f8e8d2089a84)

2. Busca el proveedor de Yuno configurado para esta tienda y ábrelo.

![Seleccionar el proveedor de Yuno](https://mintcdn.com/yuno-3979e326/z8Jixp_IwgkBlbdW/images/plugins/vtex/vtex-checkout-affiliation-2.png?fit=max\&auto=format\&n=z8Jixp_IwgkBlbdW\&q=85\&s=40b45cc111f4fdb6d56dfab6294f765b)

3. En la vista de detalle del proveedor, copia el valor del campo **Affiliation Name** y úsalo en el fragmento.

![Copiar el nombre de afiliación](https://mintcdn.com/yuno-3979e326/z8Jixp_IwgkBlbdW/images/plugins/vtex/vtex-checkout-affiliation-3.png?fit=max\&auto=format\&n=z8Jixp_IwgkBlbdW\&q=85\&s=0581aea80c9bb8ef8fb7f591892d8e96)

Después de guardar el fragmento, la experiencia mejorada queda activa. Los botones de las billeteras que configuraste
aparecerán directamente dentro del paso de pago del checkout de VTEX.

***

## Cuotas con Apple Pay

Las cuotas con Apple Pay son una función opcional dentro de la experiencia mejorada que permite a los compradores dividir su compra en cuotas.

### Qué ven los compradores

Una vez habilitada, aparece un selector **Installments** sobre el botón de Apple Pay. Al tocarlo, se abre un panel con todas las opciones de cuotas.

![Selector de cuotas](https://mintcdn.com/yuno-3979e326/z8Jixp_IwgkBlbdW/images/plugins/vtex/image-20260422-175803.png?fit=max\&auto=format\&n=z8Jixp_IwgkBlbdW\&q=85\&s=ede479b5ab84cc70d2fed3f7d5313154)

Selector de cuotas

![Panel de opciones](https://mintcdn.com/yuno-3979e326/z8Jixp_IwgkBlbdW/images/plugins/vtex/image-20260422-175811.png?fit=max\&auto=format\&n=z8Jixp_IwgkBlbdW\&q=85\&s=9b07f8a3848027a1ab26fb3bd0d4caaa)

Panel de opciones de cuotas

Si el plan incluye intereses, debajo aparece un panel **Payment details** con el desglose (número de cuotas, costo de financiamiento, etc.).

![Detalles de financiamiento](https://mintcdn.com/yuno-3979e326/z8Jixp_IwgkBlbdW/images/plugins/vtex/image-20260422-175858.png?fit=max\&auto=format\&n=z8Jixp_IwgkBlbdW\&q=85\&s=11fcb1059464a724df20da71c4af04ad)

### Cómo habilitarlas

Las cuotas con Apple Pay se habilitan desde el Yuno dashboard, creando planes de cuotas para el
método de pago Apple Pay. **El fragmento no cambia**: una tienda que ejecuta la experiencia mejorada con
`'Apple Pay'` en `paymentMethods` ya solicita a Yuno los planes disponibles en cada pedido.

**1. Crea un plan de cuotas para Apple Pay**

1. En el **Yuno dashboard**, ve a **Installments** y haz clic en **Create installment**.
2. En **Payment method type**, selecciona **Apple Pay**.
3. Define el número de cuotas, la tasa, el rango de montos y la ventana de disponibilidad.

![Crear cuotas con Payment method type definido como Apple Pay](https://mintcdn.com/yuno-3979e326/4g1NApwlhsr6lf1y/images/plugins/vtex/vtex-installments-plan-apple-pay.png?fit=max\&auto=format\&n=4g1NApwlhsr6lf1y\&q=85\&s=3c1e06e6e5d33f83f6f5560705f6f9a1)

> [!WARNING]
>
> Los planes de tarjeta no se reutilizan. Apple Pay solo ve los planes creados para el método de pago Apple Pay, por lo que
> una tienda que ya tiene planes de cuotas configurados para tarjetas aún necesita sus propios planes de Apple Pay.

**2. Revisa el plan en la lista**

El plan aparece con **Apple Pay** en la columna **Payment method**. Crea un plan por cada rango de
montos si quieres ofrecer opciones distintas según el tamaño del carrito.

![Lista de Installments con los planes de Apple Pay por rango de montos](https://mintcdn.com/yuno-3979e326/4g1NApwlhsr6lf1y/images/plugins/vtex/vtex-installments-plans-list-apple-pay.png?fit=max\&auto=format\&n=4g1NApwlhsr6lf1y\&q=85\&s=7ef91cf93f3b53c8eb0b0a9e93f34fc8)

**3. Confírmalo en tu checkout**

Abre el paso de pago con un carrito dentro del rango de montos del plan y selecciona Apple Pay. El selector
**Installments** aparece sobre el botón.

También puedes crear planes con el endpoint [Crear plan de cuotas](https://docs.y.uno/reference/installments/create-installments-plan.md),
enviando `payment_method_type: APPLE_PAY`.

### Reglas de elegibilidad

Yuno determina el plan de cada pedido a partir del total del carrito, por lo que el comprador siempre ve las opciones que
corresponden a lo que hay en su carrito. Si el carrito cambia, las opciones se recalculan.

Cada plan que creas define:

* **Payment method type**: debe ser Apple Pay.
* **Moneda y país**: deben coincidir con el pedido.
* **Rango de montos**: total mínimo y máximo del pedido que cubre el plan.
* **Ventana de disponibilidad**: fecha de inicio y de fin del plan.

El selector muestra una entrada por cada número de cuotas. Si dos planes cubren el mismo pedido y ambos
ofrecen la misma cantidad, solo se usa uno de ellos, así que mantén separados los rangos de montos si quieres un
resultado predecible.

Si ningún plan cubre el pedido, el selector se oculta y Apple Pay se muestra como un botón simple; el
pago se procesa igualmente, en una sola cuota.

> [!WARNING]
>
> Compara el monto mínimo de tu plan más bajo con el total típico de tus pedidos. Si el plan empieza
> por encima de ese total, la mayoría de los compradores nunca ve el selector, y la función parece rota cuando solo está fuera del
> rango.

***

## Cuotas con Google Pay

Las cuotas con Google Pay funcionan igual que las de Apple Pay: los compradores dividen su compra
en cuotas directamente desde la opción de pago de Google Pay. Cada billetera resuelve sus propios planes,
así que puedes ofrecer cuotas en una billetera, en la otra o en ambas.

### Qué ven los compradores

Una vez habilitada, aparece un selector **Installments** sobre el botón de Google Pay. Al tocarlo, se abre un
panel con todas las opciones de cuotas.

![Selector de cuotas sobre el botón de Google Pay](https://mintcdn.com/yuno-3979e326/YcgdVMpdBS1BXBKt/images/plugins/vtex/vtex-google-pay-installments-selector.png?fit=max\&auto=format\&n=YcgdVMpdBS1BXBKt\&q=85\&s=a31ef8abadb41382571180b03556f8f2)

Selector de cuotas

![Panel de opciones de cuotas de Google Pay](https://mintcdn.com/yuno-3979e326/YcgdVMpdBS1BXBKt/images/plugins/vtex/vtex-google-pay-installments-options.png?fit=max\&auto=format\&n=YcgdVMpdBS1BXBKt\&q=85\&s=8941d5c80ac9dc06df934db2d1a5f299)

Panel de opciones de cuotas

Si el plan incluye intereses, debajo aparece un panel **Payment details** con el desglose
(número de cuotas, costo de financiamiento, etc.), exactamente igual que con Apple Pay.

### Cómo habilitarlas

Las cuotas con Google Pay se habilitan desde el Yuno dashboard, creando planes de cuotas para el
método de pago Google Pay. **El fragmento no cambia**: una tienda que ejecuta la experiencia mejorada
con `'Google Pay'` en `paymentMethods` ya solicita a Yuno los planes disponibles en cada pedido.

**1. Crea un plan de cuotas para Google Pay**

1. En el **Yuno dashboard**, ve a **Installments** y haz clic en **Create installment**.
2. En **Payment method type**, selecciona **Google Pay**.
3. Define el número de cuotas, la tasa, el rango de montos y la ventana de disponibilidad.

![Crear cuotas con Payment method type definido como Google Pay](https://mintcdn.com/yuno-3979e326/YcgdVMpdBS1BXBKt/images/plugins/vtex/vtex-installments-plan-google-pay.png?fit=max\&auto=format\&n=YcgdVMpdBS1BXBKt\&q=85\&s=5825098727d02f0dc5669d88515c8802)

> [!WARNING]
>
> Los planes son estrictamente por método de pago. Google Pay solo ve los planes creados para el
> método de pago Google Pay; no se reutilizan ni los planes de tarjeta ni los de Apple Pay. Una tienda que ofrece
> cuotas en dos o más billeteras necesita un conjunto de planes por cada billetera.

**2. Revisa el plan en la lista**

El plan aparece con **Google Pay** en la columna **Payment method**. Crea un plan por cada rango de
montos si quieres ofrecer opciones distintas según el tamaño del carrito.

![Lista de Installments con los planes de Google Pay por rango de montos](https://mintcdn.com/yuno-3979e326/YcgdVMpdBS1BXBKt/images/plugins/vtex/vtex-installments-plans-list-google-pay.png?fit=max\&auto=format\&n=YcgdVMpdBS1BXBKt\&q=85\&s=72687cd3d0f5a2fd395b751080a5b8f4)

**3. Confírmalo en tu checkout**

Abre el paso de pago con un carrito dentro del rango de montos del plan y selecciona Google Pay. El selector
**Installments** aparece sobre el botón.

También puedes crear planes con el endpoint [Crear plan de cuotas](https://docs.y.uno/reference/installments/create-installments-plan.md),
enviando `payment_method_type: GOOGLE_PAY`.

### Reglas de elegibilidad

Google Pay sigue las mismas [reglas de elegibilidad que Apple Pay](#eligibility-rules): Yuno determina el
plan de cada pedido a partir del total del carrito, lo recalcula cuando el carrito cambia y asocia los planes según
moneda, país, rango de montos y ventana de disponibilidad. La única diferencia es el tipo de método de
pago: un plan solo se aplica a Google Pay cuando su **Payment method type** es **Google Pay**.

Si ningún plan cubre el pedido, el selector se oculta y Google Pay se muestra como un botón simple; el
pago se procesa igualmente, en una sola cuota.

***

## Cuotas con Samsung Pay

Las cuotas con Samsung Pay funcionan igual que las de Apple Pay y Google Pay: los compradores dividen
su compra en cuotas directamente desde la opción de pago de Samsung Pay.

### Qué ven los compradores

Una vez habilitada, aparece un selector **Installments** sobre el botón de Samsung Pay. Al tocarlo, se abre un panel con todas las opciones de cuotas, con un desglose completo del financiamiento debajo.

![Página de checkout de Samsung Pay con la confirmación biométrica, el selector de cuotas y los detalles del pago](https://mintcdn.com/yuno-3979e326/NyQXrSTq_qEgQGLB/images/plugins/vtex/vtex-samsung-pay-checkout-staging.png?fit=max\&auto=format\&n=NyQXrSTq_qEgQGLB\&q=85\&s=8897b503e1fc0c56c9dac1d403eeff8b)

Checkout de Samsung Pay con cuotas

### Cómo habilitarlas

Las cuotas con Samsung Pay se habilitan desde el Yuno dashboard, creando planes de cuotas para el
método de pago Samsung Pay. **El fragmento no cambia**: una tienda que ejecuta la experiencia mejorada
con `'Samsung Pay'` en `paymentMethods` ya solicita a Yuno los planes disponibles en cada pedido.

**1. Crea un plan de cuotas para Samsung Pay**

1. En el **Yuno dashboard**, ve a **Installments** y haz clic en **Create installment**.
2. En **Payment method type**, selecciona **Samsung Pay**.
3. Define el número de cuotas, la tasa, el rango de montos y la ventana de disponibilidad.

![Crear cuotas con Payment method type definido como Samsung Pay](https://mintcdn.com/yuno-3979e326/NyQXrSTq_qEgQGLB/images/plugins/vtex/vtex-installments-plan-samsung-pay.png?fit=max\&auto=format\&n=NyQXrSTq_qEgQGLB\&q=85\&s=e2de6f41fbe63c171be537da9ccdba4a)

> [!WARNING]
>
> Los planes son estrictamente por método de pago. Samsung Pay solo ve los planes creados para el
> método de pago Samsung Pay; no se reutilizan ni los planes de tarjeta ni los de Apple Pay o Google Pay. Una tienda que ofrece
> cuotas en varias billeteras necesita un conjunto de planes por cada billetera.

**2. Revisa el plan en la lista**

El plan aparece con **Samsung Pay** en la columna **Payment method**. Crea un plan por cada rango de
montos si quieres ofrecer opciones distintas según el tamaño del carrito.

![Lista de Installments con los planes de Samsung Pay por rango de montos](https://mintcdn.com/yuno-3979e326/NyQXrSTq_qEgQGLB/images/plugins/vtex/vtex-installments-plans-list-samsung-pay.png?fit=max\&auto=format\&n=NyQXrSTq_qEgQGLB\&q=85\&s=f6a5042bf69cc7d8a037332cce36a565)

**3. Confírmalo en tu checkout**

Abre el paso de pago con un carrito dentro del rango de montos del plan y selecciona Samsung Pay. El selector
**Installments** aparece sobre el botón.

También puedes crear planes con el endpoint [Crear plan de cuotas](https://docs.y.uno/reference/installments/create-installments-plan.md),
enviando `payment_method_type: SAMSUNG_PAY`.

### Reglas de elegibilidad

Samsung Pay sigue las mismas [reglas de elegibilidad que Apple Pay](#eligibility-rules): Yuno determina el
plan de cada pedido a partir del total del carrito, lo recalcula cuando el carrito cambia y asocia los planes según
moneda, país, rango de montos y ventana de disponibilidad. La única diferencia es el tipo de método de
pago: un plan solo se aplica a Samsung Pay cuando su **Payment method type** es **Samsung Pay**.

Si ningún plan cubre el pedido, el selector se oculta y Samsung Pay se muestra como un botón simple; el
pago se procesa igualmente, en una sola cuota.

### Visualización de pedidos en VTEX

> [!WARNING]
>
> Actualmente VTEX muestra los pedidos de Samsung Pay como un **pago único completo** en el resumen del pedido y en los
> paneles de administración. En VTEX aún no existe una configuración nativa de cuotas para Samsung Pay; el ticket 1453437 de VTEX
> lo registra como una mejora futura.
>
> *Yuno es la fuente de verdad* del desglose de cuotas: el número correcto de cuotas,
> el monto por cuota y los intereses, si los hay, se pueden ver en el Yuno dashboard y en los
> detalles de la transacción. La visualización de VTEX es solo estética y no afecta cómo se procesa
> ni se liquida el pago.


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