> ## 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 campos de afiliación

> Todos los campos del formulario del proveedor Yuno en VTEX, con su formato, valor predeterminado, versión mínima del plugin y un ejemplo.

Estos son los campos del formulario del proveedor Yuno en VTEX, en **Store Settings → Payment → Providers**, dentro de tu afiliación de Yuno. La [guía de configuración](https://docs.y.uno/es/docs/plugins/vtex/set-up-yuno-on-vtex.md) muestra dónde está el formulario y qué campos agrega el propio VTEX.

## Affiliation Name

Un nombre legible para esta integración con Yuno.

* **Obligatorio**: Sí

Ves este nombre cuando eliges el proveedor en una condición de pago, así que elige uno que distinga tus afiliaciones, por ejemplo por país o por la cuenta de Yuno que usan.

**Ejemplo**: `Yuno Brazil`

## Account ID

Tu **Account ID** de Yuno.

* **Obligatorio**: Sí

Encuéntralo en tu Dashboard de Yuno, en **Developers → API Credentials**.

**Ejemplo**: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`

## Public API Key

Tu **Public API Key** de Yuno.

* **Obligatorio**: Sí

Encuéntrala en tu Dashboard de Yuno, en **Developers → API Credentials**. Su prefijo define el entorno de Yuno que usa la tienda: `dev_`, `staging_`, `sandbox_` o `prod_`.

**Ejemplo**: `sandbox_pub-xxxxxxxx`

## Private Secret Key

Tu **Private Secret Key** de Yuno.

* **Obligatorio**: Sí

Encuéntrala en tu Dashboard de Yuno, en **Developers → API Credentials**. Debe pertenecer a la misma cuenta y al mismo entorno que la Public API Key.

**Ejemplo**: `xxxxxxxxxxxxxxxxxxxxxxxx`

## Main Account Name

La cuenta de VTEX que es dueña de los datos de los pedidos, para configuraciones con varias cuentas.

* **Obligatorio**: No. Déjalo vacío en una tienda de una sola cuenta.

El plugin lee los pedidos y los grupos de pedidos de esta cuenta. Configúralo junto con **Main Account App key** y **Main Account App token**: si alguno de los tres está vacío, el plugin ignora los tres. Consulta [Multi-account](https://docs.y.uno/es/docs/plugins/vtex/advanced-features.md#multi-account) para saber qué configuraciones lo necesitan.

**Ejemplo**: `mystoreparent`

## Main Account App key

Application Key de la cuenta principal de VTEX.

* **Obligatorio**: No. Solo junto con **Main Account Name**.

El plugin la usa para llamar a las API de VTEX en nombre de la cuenta principal. Consulta [Multi-account](https://docs.y.uno/es/docs/plugins/vtex/advanced-features.md#multi-account).

**Ejemplo**: `vtexappkey-mystoreparent-XXXXXX`

## Main Account App token

Application Token de la cuenta principal de VTEX.

* **Obligatorio**: No. Solo junto con **Main Account Name**.

Va en pareja con **Main Account App key**. Consulta [Multi-account](https://docs.y.uno/es/docs/plugins/vtex/advanced-features.md#multi-account).

**Ejemplo**: `XXXXXXXXXXXXXXXXXXXXXXXX`

## Soft Descriptor

Texto personalizado que aparece en el resumen de la tarjeta del comprador.

* **Obligatorio**: No

**Ejemplo**: `MYSTORE*ORDER`

## Create Customer

Crea un registro de cliente en Yuno para cada comprador.

* **Obligatorio**: No

Cuando se establece en **Yes**, el plugin crea el registro de cliente correspondiente en Yuno. **Vault Card for Order Modification** y **Enable Network Tokens** lo necesitan.

**Ejemplo**: `Yes`

## VTEX IO orderPlaced page URL

Dónde llegan los compradores después del pago.

* **Obligatorio**: No

Una URL personalizada a la que se redirige a los compradores después del pago.

**Ejemplo**: `https://www.example.com/checkout/orderPlaced`

## Payment Mode

Cómo paga el comprador: dentro del checkout o en una página de redirección.

* **Obligatorio**: No

Elige **Payment App** para mostrar el pago dentro del checkout de VTEX, o **Legacy** para las tiendas con el checkout Legacy de VTEX, que no puede mostrar una Payment App: en ese caso se redirige al comprador a una página de pago alojada por Yuno. El valor predeterminado es **Payment App**.

**Ejemplo**: `Payment App`

## Transaction Identification From

Qué ID de transacción muestra el pedido.

* **Obligatorio**: No

Elige **Yuno TID** para mostrar el ID de transacción de Yuno, o **Provider TID** para mostrar el ID de transacción asignado por el proveedor de pago que procesó el pago. Cuando el proveedor no envía un ID de transacción, se muestra el ID de Yuno. El valor predeterminado es **Yuno TID**.

**Ejemplo**: `Yuno TID`

## Antifraud Providers for Split Orders

Qué proveedores antifraude reciben la sesión compartida en los pedidos divididos.

* **Obligatorio**: No
* **Valor predeterminado**: los cuatro proveedores en el plugin **4.2.362 o posterior**; `RISKIFIED` y `CYBERSOURCE` en versiones anteriores.

Escribe una lista separada por comas con `RISKIFIED`, `CYBERSOURCE`, `SIGNIFYD` y `CIELO_CYBERSOURCE_FRAUD`. Si la completas, solo los proveedores que incluyas reciben la sesión.

**Ejemplo**: `RISKIFIED,CYBERSOURCE`

## Vault Card for Order Modification

Permite que el plugin cobre la diferencia cuando aumenta el total de un pedido.

* **Obligatorio**: No. Necesita **Create Customer** en **Yes**.

Cuando se establece en **Yes**, el plugin almacena de forma segura la tarjeta usada en cada pedido y cobra el monto adicional automáticamente si el total del pedido aumenta después. Es el único campo que autoriza cobros adicionales: cuando está en **No**, un aumento del total del pedido se rechaza aunque la tarjeta se haya almacenado para network tokens. Consulta [Order modifications](https://docs.y.uno/es/docs/plugins/vtex/advanced-features.md#order-modifications-changed-order-totals).

**Ejemplo**: `Yes`

## Enable Network Tokens

Almacena tarjetas para que las compras repetidas puedan usar un network token.

* **Obligatorio**: No. Necesita **Create Customer** en **Yes**.

Cuando se establece en **Yes**, el plugin almacena de forma segura cada tarjeta en su primera compra y la reconoce en compras posteriores del mismo cliente, de modo que Yuno pueda procesar las compras repetidas con un network token en lugar del número de la tarjeta.

> [!WARNING]
>
> La opción no tiene efecto hasta que Yuno active los network tokens en las rutas que usa tu tienda. Hasta entonces las tarjetas se almacenan, pero no se emite ningún token. Contacta a tu KAM de Yuno o a soporte para activarlo.

Consulta [Network tokens](https://docs.y.uno/es/docs/plugins/vtex/advanced-features.md#network-tokens-repeat-card-purchases).

**Ejemplo**: `Yes`

## Use Corporate Buyer Data

Paga los pedidos de empresas con el nombre y el CNPJ de la empresa. Solo Brasil.

* **Obligatorio**: No
* **Valor predeterminado**: `No`

Cuando se establece en **Yes**, los pedidos hechos por un comprador que paga como empresa (*pessoa jurídica*) se pagan con la razón social y el **CNPJ** de la empresa en lugar del nombre personal y el CPF del comprador, en todos los métodos de pago. Consulta [Corporate purchases](https://docs.y.uno/es/docs/plugins/vtex/advanced-features.md#corporate-purchases-brazil).

**Ejemplo**: `Yes`

## Headless Payment Handoff

Para marketplaces cuyo propio checkout headless crea el pago de Yuno.

* **Obligatorio**: No
* **Valor predeterminado**: `No`
* **Disponible en el plugin**: **4.2.356 o posterior** para tarjetas, **4.2.361 o posterior** para PIX

Es una configuración avanzada para marketplaces que ejecutan su propio checkout headless y crean ellos mismos el pago de Yuno, para un carrito que mezcla productos de la propia tienda y vendedores del marketplace de VTEX. Actívala solo con la guía del equipo de Yuno.

Cuando se establece en **Yes**, el plugin no crea nada en Yuno. Cada autorización te entrega una solicitud de pago de Yuno lista para enviar, de solo autorización, para la parte del carrito que corresponde a VTEX. Tú agregas el token de la tarjeta y la división del marketplace, y creas un único pago que cubre todos los pedidos de vendedores del carrito. Luego el plugin informa el estado de cada pedido a partir de ese pago y captura o reembolsa por separado la parte de cada pedido.

Solo tarjetas y PIX: cualquier otro método de pago se rechaza.

**Ejemplo**: `Yes` en la tienda que ejecuta el checkout headless. Todas las demás tiendas dejan `No`.

## Store Base Path

El prefijo de la ruta URL de una tienda que no se sirve desde la raíz del dominio.

* **Obligatorio**: No
* **Disponible en el plugin**: **4.2.316 o posterior**

Úsalo para una tienda en `https://www.example.com/br` en lugar de la raíz del dominio. Es la ruta que usa la Payment App cuando llama a las rutas de pago de tu tienda durante el checkout. Déjalo vacío cuando la tienda se sirva desde la raíz del dominio.

* Usa solo segmentos de ruta simples: letras, números, `-` y `_`. Sin esquema, host, query string ni puntos.
* Se agrega una barra inicial si falta.
* Un valor que parece un nombre de host se ignora, y la tienda se comporta como si el campo estuviera vacío.

**Ejemplo**: `/br` o `/br/store`

## Send Order Sequence as Merchant Reference

Envía la secuencia del pedido de VTEX como referencia del comercio del pago.

* **Obligatorio**: No
* **Valor predeterminado**: `No`
* **Disponible en el plugin**: **4.2.333 o posterior** para PIX, boleto y los demás métodos creados en el servidor; **4.2.355 o posterior** para todos los métodos de pago

Cuando se establece en **Yes**, cada pago envía la secuencia del pedido de VTEX (el número que aparece en la lista de pedidos de VTEX, por ejemplo `1234567890123`) como referencia del comercio del pago. Un proveedor configurado con una identificación de transacción personalizada, como Mercado Pago, muestra entonces esa secuencia como referencia externa en su panel, igual que antes de migrar a Yuno.

Cuando se establece en **No**, o cuando la secuencia no está disponible, la referencia es el ID del pedido de VTEX.

**Ejemplo**: `Yes`

## Sales Channel Domains

Asocia cada canal de ventas con el dominio de su tienda.

* **Obligatorio**: No
* **Disponible en el plugin**: **4.2.333 o posterior**

Asocia el ID de cada canal de ventas de VTEX (política comercial) con el dominio público de su tienda, de modo que el pago informe la tienda de la que vino el pedido en lugar del host predeterminado de la cuenta. Esto mejora los reportes y la conciliación en las tiendas que ejecutan varias tiendas en una sola cuenta.

* Escribe pares `id=domain` separados por `;`. También se aceptan una `,` entre pares y `:` entre el ID y el dominio.
* Se elimina el prefijo `https://` y las barras finales, y los pares mal formados se omiten.
* Los canales de ventas que no incluyas usan el host de la tienda del propio pedido. Las tiendas que dejan el campo vacío mantienen el comportamiento actual.

**Ejemplo**:

```text theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
1=www.example.com;2=b2b.example.com;18=members.example.com
```

## Delay To Cancel

Cuánto espera VTEX un pago pendiente, por método de pago, antes de cancelar el pedido.

* **Obligatorio**: No
* **Valor predeterminado**: la ventana de cada método de pago, indicada en [Cuánto espera VTEX un pago pendiente](#how-long-vtex-waits-for-a-pending-payment)
* **Disponible en el plugin**: **4.2.373 o posterior**; el par `Pix` **4.2.379 o posterior**

Cuando un pago sigue pendiente, VTEX espera un tiempo determinado antes de cancelar el pedido y liberar su stock. Este campo define ese tiempo por método de pago.

* Escribe pares `Method=seconds` separados por `;`. También se aceptan una `,` entre pares y `:` entre el nombre y los segundos.
* `Method` es el nombre del método de pago tal como aparece cuando creas una condición de pago en VTEX (por ejemplo `Mastercard`, `MercadoPagoPro` o `Pagaleve Transparente`), no el nombre que le das a la condición. La lista completa está en [Métodos de pago que puedes definir en Delay To Cancel](#payment-methods-you-can-set-in-delay-to-cancel).
* Los nombres se comparan sin distinguir mayúsculas de minúsculas, pero los acentos deben coincidir, como en `Elo Débito`.
* `Cards` se aplica a todas las marcas de tarjeta, y el par propio de una marca tiene prioridad sobre `Cards`.
* Los segundos deben ser un número entero entre `600` (10 minutos) y `2592000` (30 días). Un par fuera de ese rango, o mal formado, se ignora y el método mantiene su valor predeterminado.
* Las tarjetas y los métodos que renderiza Yuno (Apple Pay, Google Pay, Samsung Pay, Click to Pay) nunca esperan menos de una hora: un valor menor se convierte en una hora.
* Para las tarjetas, el valor también reemplaza la ventana de 3 días de un pago con tarjeta que ya existe y sigue pendiente (revisión antifraude o desafío de la tarjeta). Por lo tanto, un valor corto cancela revisiones que se habrían aprobado más tarde.
* `Pix` define la ventana de PIX en el checkout con Payment App, dentro de los [límites de PIX de VTEX](https://developers.vtex.com/docs/api-reference/payment-provider-protocol#post-/payments) de 15 minutos a 1 hora. De `900` a `3600` el valor se usa tal como se escribe, de `600` a `899` se convierte en 15 minutos, y por encima de `3600` se convierte en 1 hora. Sin un par `Pix`, o con un valor menor que `600`, que se ignora como cualquier otro par, la ventana es de 1 hora.
* Boleto Bancário no se puede configurar: sigue su fecha de vencimiento.
* En el handoff de pago headless, desde el plugin **4.2.376**, PIX siempre espera 15 minutos, cuando vence su código QR, y las tarjetas esperan según el par `Cards` o el de la marca (al menos 1 hora) o 24 horas si no hay ninguno.

**Ejemplo**: las tarjetas esperan 3 días y PIX 15 minutos.

```text theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
Cards=259200;Pix=900
```

### Vencimiento del código QR de PIX

En el checkout con Payment App, el plugin le pide al proveedor un código QR de PIX que vence con la ventana de PIX, de modo que el código QR deja de poder pagarse cuando VTEX cancela el pedido sin pagar. Que el proveedor respete ese vencimiento determina qué debes configurar.

| Proveedor | Vencimiento del código QR | Qué configurar |
| :- | :- | :- |
| Mercado Pago, PagBank | La ventana de PIX. Reemplaza el vencimiento definido en la conexión del proveedor, también cuando el de la conexión es más corto: un código QR de 15 minutos pasa a 1 hora. | Para mantener un código QR de menos de 1 hora, define un par `Pix`, por ejemplo `Pix=900`. |
| Pagar.me | La ventana de PIX; si la conexión tiene `Transactions expire time` definido, el más corto de los dos. | Define un par `Pix` o `Transactions expire time` para acortarlo. |
| Santander, PicPay, Itaú, Pinbank, Pay4Fun, dLocal | El vencimiento definido en la conexión del proveedor; el par `Pix` no llega al código QR. VTEX espera ese vencimiento, entre 15 minutos y 1 hora, o la ventana de PIX cuando el proveedor no informa ningún vencimiento. | Define el vencimiento de PIX de la conexión en 60 minutos o menos. Un código QR más largo todavía se puede pagar después de que VTEX cancele el pedido. |

El checkout con redirección (Legacy) y Pagaleve Pix A Vista no usan la ventana de PIX: el código QR conserva el vencimiento de la conexión, por lo que allí se aplica la misma regla de 60 minutos.

### Cuánto espera VTEX un pago pendiente

Sin el campo **Delay To Cancel**, cada método de pago usa la ventana de abajo en el plugin **4.2.372 o posterior**. Las versiones anteriores esperaban hasta 24 horas para las billeteras, y algunas respuestas pendientes no traían ninguna ventana. El campo reemplaza la ventana de todos los métodos excepto Boleto Bancário; el par `Pix` se aplica solo en el checkout con Payment App.

| Método de pago | Ventana predeterminada |
| :- | :- |
| Tarjetas y MONNET | 24 horas. Un pago con tarjeta que ya existe y está en revisión (revisión antifraude o desafío de la tarjeta) recibe 3 días. |
| Boleto Bancário | La fecha de vencimiento del boleto, con un mínimo de 24 horas. |
| PIX | El vencimiento del código QR, entre 15 minutos y 1 hora. En el plugin **4.2.379 o posterior**, los códigos QR de Mercado Pago, PagBank y Pagar.me vencen después de 1 hora de forma predeterminada; consulta [Vencimiento del código QR de PIX](#pix-qr-code-expiration). |
| Apple Pay, Google Pay, Samsung Pay, Click to Pay y los demás métodos que renderiza Yuno, PicPay, MercadoPagoPro, Nubank, Pagaleve | 1 hora. |

En el checkout con redirección (Legacy) los valores predeterminados son distintos: PIX, PicPay, MercadoPagoPro y Nubank esperan 1 hora, y todos los demás métodos, boleto incluido, 24 horas. Desde el plugin **4.2.376**, el handoff de pago headless espera 15 minutos para PIX y 24 horas para las tarjetas.

### Métodos de pago que puedes definir en Delay To Cancel

Escribe el nombre exactamente como lo muestra VTEX cuando creas la condición de pago. No importan las mayúsculas y minúsculas; los acentos y los espacios sí. Un valor menor que la espera más corta de su grupo se eleva a esa espera, y un valor de `Pix` mayor que 1 hora se reduce a 1 hora.

| Grupo | Nombres | Espera mínima |
| :- | :- | :- |
| `Cards`, o una marca de tarjeta | Visa, Mastercard, American Express, Diners, Elo, Hipercard, Discover, JCB, Aura, Alelo, Privatelabels, Cobranded, Visa Electron, Débito Online, Maestro, Mastercard Debit, VirtualDebitElo, Elo Débito, Voucher. El par propio de una marca tiene prioridad sobre `Cards`. En el checkout con redirección (Legacy), `Cards` también cubre Yuno Card. | 1 hora |
| Métodos que renderiza Yuno | Apple Pay, Google Pay, Samsung Pay, C2P, Yuno C2P Golden, Fast payments with Mercado Pago, PSE, Safetypay, PagoEfectivo, Yuno Card, Yuno Wallet, Yuno Bank Transfer, Yuno Buy Now Pay Later, Yuno Payment Link, Yuno Ticket, y cualquier otro nombre de método que no figure aquí. | 1 hora |
| `Pix` | Pix. Solo en el checkout con Payment App, plugin **4.2.379 o posterior**. Un valor mayor que 1 hora pasa a ser 1 hora. | 15 minutos |
| Métodos creados en el servidor | Nubank, PicPay, MercadoPagoPro, Pagaleve Transparente, Pagaleve Pix A Vista Transparente, MONNET - CASH, MONNET - BANK TRANSFER. | 10 minutos |
| No configurable | Boleto Bancário (sigue la fecha de vencimiento). En el checkout con redirección (Legacy), Yuno Ticket es un boleto y no se puede configurar tampoco. | |


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