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

# Pagos Web

> Integra flujos de pago de full-checkout en Web, desde la inicialización del SDK hasta el manejo del reintento de pago

> [!NOTE]
>
> **Esta página documenta un SDK heredado.** ¿Vas a iniciar una nueva integración? Usa el [Yuno SDK](https://docs.y.uno/es/docs/yuno-sdk/get-started.md). ¿Ya usas un SDK heredado? Sigue la [guía de migración](https://docs.y.uno/es/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.

El SDK Web facilita integrar flujos de pago en tus experiencias web y basadas en navegador.

## Recursos adicionales

* Yuno ofrece una [biblioteca de TypeScript](https://www.npmjs.com/package/@yuno-payments/sdk-web-types) que complementa el SDK.
* Consulta [Elegir integración](https://docs.y.uno/es/docs/sdks/overview/choose-integration.md) si no estás seguro de qué flujo seguir.
* Consulta la [app de demostración](https://github.com/yuno-payments/yuno-sdk-web) para ver una implementación completa (clónala desde el repositorio).

## Requisitos

* Un [cliente](https://docs.y.uno/es/reference/customers/create-customer.md) creado en Yuno y una [sesión de checkout](https://docs.y.uno/es/reference/checkout-sessions/create-checkout-session.md): consulta cada API al configurar tu backend.
* Clave de API pública (obtenla en el [Yuno Dashboard](https://dashboard.y.uno/) → **Developers** > **Credentials**)

El primer paso es incluir la biblioteca en tu proyecto. La guía de integración ofrece tres métodos flexibles:

1. **Inclusión directa del script en HTML**: agrega la etiqueta script a tu página.
2. **Inyección dinámica de JavaScript**: carga el SDK en tiempo de ejecución.
3. **Instalación del módulo NPM**: instálalo con npm (recomendado).

**Opción 1: NPM (recomendada)**

```bash theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
npm install @yuno-payments/sdk-web
```

Al usar el paquete NPM, `loadScript` inyecta el script del SDK y se resuelve con el objeto `Yuno`. Pasa `sri: true` para que el navegador verifique el script contra su hash publicado. La inicialización es un paso aparte: llama a `Yuno.initialize` con tu clave de API pública para obtener la instancia que usarás en el resto de la integración.

```javascript theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
import { loadScript } from '@yuno-payments/sdk-web';

const Yuno = await loadScript({ sri: true });
const yuno = await Yuno.initialize('YOUR_PUBLIC_KEY');
```

> [!TIP]
>
> `loadScript()` solo empieza a descargar el SDK cuando tu app lo llama. Agrega un preload para `main.js` y preconnects a los hosts de Yuno en el `<head>` de tu HTML para que la descarga empiece mientras carga la página. Consulta [Precargar el script del SDK](https://docs.y.uno/es/docs/sdks/resources/references/web.md#preload-the-sdk-script).

**Opción 2: etiqueta script de HTML**

```html theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
<script 
  src="https://sdk-web.y.uno/v1.10/main.js"
  async
  defer
></script>
```

> [!NOTE]
>
> `v1.10` es una ruta global: recibe todos los parches publicados en esa línea, así que obtienes correcciones sin cambiar tu integración.
>
> No agregues un atributo `integrity` a esta URL. Como el archivo se vuelve a publicar con cada parche, cualquier hash que fijes deja de coincidir y el navegador bloquea el script. Subresource Integrity requiere la URL inmutable de la versión completa; consulta [Subresource Integrity](https://docs.y.uno/es/docs/sdks/resources/references/web.md#subresource-integrity-sri).

**Opción 3: JavaScript dinámico**

```javascript theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
const script = document.createElement('script');
script.src = 'https://sdk-web.y.uno/v1.10/main.js';
script.async = true;
script.defer = true;
document.head.appendChild(script);
```

Una vez completado el paso 1, continúa con la integración de full-checkout.

## Parámetros

Estos son los parámetros que cubre esta guía. Para ver la lista completa de parámetros y callbacks, consulta la [Referencia común del SDK Web](https://docs.y.uno/es/docs/sdks/resources/references/web.md).

| Parámetro | Descripción |
| - | - |
| `checkoutSession` | ID de la sesión de checkout desde tu backend (API Crear sesión de checkout). Obligatorio en todos los flujos. |
| `elementSelector` | Selector CSS del elemento donde se monta el SDK (p. ej. `#root`). |
| `countryCode` | Código de país ISO donde se procesa el pago (p. ej. `FR`, `US`). |
| `language` | Código de idioma de la interfaz (p. ej. `fr-FR`, `ar`). Opcional; por defecto usa el idioma del navegador cuando está disponible. |
| `showLoading` | Muestra el indicador de carga del SDK. Opcional. |
| `showPaymentStatus` | Muestra la pantalla de resultado del pago. Opcional. |
| `createPayment(oneTimeToken, tokenWithInformation)` | Callback: envía el token de un solo uso a tu backend para crear el pago (acepta `tokenWithInformation`, que coincide con el [esquema de la respuesta del token del SDK checkout](https://docs.y.uno/es/reference/checkout-sessions/create-one-time-use-token-sdk-checkout)); luego llama a `await yuno.continuePayment()`. |
| `paymentResult(status, subStatus)` | Callback: el pago finalizó. Recibe el [estado del pago](https://docs.y.uno/es/reference/payments/status-and-response-codes/payment.md) (p. ej. `SUCCEEDED`, `DECLINED`, `PENDING`) y un `subStatus` opcional que lo califica. Consulta [Pasos cancelados por el comprador](https://docs.y.uno/es/docs/sdks/resources/references/web.md#shopper-cancelled-steps). |
| `error(message, data)` | Callback: error durante el flujo. |
| `onLoading` | Callback: actualizaciones del estado de carga. |
| `onChange` | Informa si el formulario de pago está completo. Recibe `{ form: { isValid } }`. Úsalo con `showPayButton: false` para controlar tu propio botón de pago. Disponible desde v1.10.11. |
| `card` | Opciones del formulario de tarjeta (p. ej. `onChange`, `isCreditCardProcessingOnly`). Opcional. |

## full-checkout

Implementa la integración Full de Yuno: interfaz de checkout prediseñada con control total sobre la marca, los formularios y el flujo. Úsala cuando quieras que Yuno renderice la experiencia de checkout mientras tú gestionas la creación del cliente y de la sesión de checkout en tu backend.

### Paso 1: incluye la biblioteca en tu proyecto

Sigue los pasos de [Incluir la biblioteca en tu proyecto](#include-the-library-in-your-project) más arriba.

### Paso 2: inicializa el SDK

Después de incluir la biblioteca ([paso 1](#step-1-include-the-library-in-your-project)), inicializa el SDK. Consulta la [Guía de inicio rápido](https://docs.y.uno/es/docs/sdks/overview/quickstart.md#web-sdk-integration) para la inicialización.

### Paso 3: inicia el proceso de checkout

Usa la función `await yuno.startCheckout()` para iniciar el proceso de checkout con los parámetros necesarios.

Consulta [Parámetros](#parameters) para ver todas las opciones. Para estilos, temas y configuraciones adicionales, consulta [Personalizaciones del SDK](https://docs.y.uno/es/docs/sdks/resources/references/web.md).

```javascript theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
await yuno.startCheckout({
  checkoutSession: "438413b7-4921-41e4-b8f3-28a5a0141638",
  elementSelector: "#root",
  countryCode: "FR",
  language: "fr-FR",
  showLoading: true,
  issuersFormEnable: true,
  showPaymentStatus: true,
  card: {
    isCreditCardProcessingOnly: true,
    onChange: ({ error, data }) => {
      if (error) {
        console.log('Card form error:', error);
      } else {
        console.log('Card form data:', data);
      }
    },
  },
  onLoading: (args) => {
    console.log(args);
  },
  onPaymentMethodSelected: () => {
    console.log("Payment method selected");
  },
  paymentResult: (status) => {
    console.log("Payment result:", status);
  },
  error: (message, data) => {
    console.error("Payment error:", message, data);
  },
  async createPayment(oneTimeToken) {
    await createPayment({ oneTimeToken, checkoutSession });
    await yuno.continuePayment({ showPaymentStatus: true });
  },
});
```

Por defecto, el SDK de Yuno se renderiza como un modal. Puedes especificar el elemento donde se renderizará el SDK. Consulta [Modo de renderizado](https://docs.y.uno/es/docs/sdks/resources/references/web.md#render-mode) para más detalles.

Para todos los APM (Google Pay, Apple Pay, PayPal), `onPaymentMethodSelected` se activa cuando el cliente elige el método de pago (antes de que comience el flujo de pago). Define `onPaymentMethodSelected` en `await yuno.startCheckout()` antes de `await yuno.mountCheckout()`. En PayPal, la hoja de pago se abre inmediatamente después de la selección, sin necesidad de un clic de confirmación adicional.

### Paso 4: monta el SDK

Muestra los métodos de pago:

```javascript theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
await yuno.mountCheckout();
```

### Paso 5: inicia el proceso de pago

Llama a `await yuno.startPayment()` para iniciar el flujo de pago después de que el usuario seleccione un método de pago:

```javascript theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
const PayButton = document.querySelector("#button-pay");

PayButton.addEventListener("click", async () => {
  await yuno.startPayment();
});
```

### Paso 6: obtén el OTT (token de un solo uso)

Después de que el cliente completa los datos solicitados en los formularios de pago de Yuno, el SDK entrega el token de un solo uso. Entonces se activa la función de configuración `createPayment(oneTimeToken)` con el token de un solo uso.

```javascript theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
createPayment(oneTimeToken);
```

También puedes usar `tokenWithInformation` (o inspeccionarlo como segundo argumento) para recibir información adicional que el cliente proporcionó en el checkout (que coincide con el [esquema del token del SDK checkout](https://docs.y.uno/es/reference/checkout-sessions/create-one-time-use-token-sdk-checkout)), como cuotas, tipo y número de documento o, en transferencias ACH, `tokenWithInformation.bank_transfer?.bank_name` (SDK Web 1.11.24 / 1.10.26; los números de cuenta y de ruta nunca se devuelven):

```javascript theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
async function createPayment(oneTimeToken, tokenWithInformation) {
  // Read ACH bank name if needed:
  const bankName = tokenWithInformation.bank_transfer?.bank_name;
  
  await createPayment({ oneTimeToken, checkoutSession });
  await yuno.continuePayment({ showPaymentStatus: true });
}
```

Cuando una [promoción](https://docs.y.uno/es/docs/payment-features/promotions) aplica a la tarjeta, `tokenWithInformation.quote` contiene su línea de descuento, `{ "type": "YUNO_PROMOTION", "quote_id": "…" }`. Envíala con el token a tu backend y agrégala al pago en el paso 7. Consulta [Promociones](https://docs.y.uno/es/docs/sdks/resources/references/web.md#promotions).

Usa el loader predeterminado de Yuno o implementa el tuyo con la configuración requerida.

### Paso 7: crea el pago

Crea un pago con el [endpoint Crear pago](https://docs.y.uno/es/reference/payments/create-payment.md). El backend del comercio debe llamar a este endpoint para crear el pago en Yuno usando el token de un solo uso y la sesión de checkout. Si `tokenWithInformation.quote` estaba presente, envía el `amount` original y agrega esa línea tal cual: `additional_data.order.discounts: [{ "type": "YUNO_PROMOTION", "quote_id": "<quote_id>" }]`, o el pago se cobra completo.

Después del paso 6, el flujo básico de pago está implementado. Prueba con la sesión de checkout y el token de un solo uso. Para funciones adicionales, consulta [Funciones complementarias](#complementary-features).

**Obligatorio**: después de crear un pago, integra el método `continuePayment`. Cuando la respuesta de la API establece `sdk_action_required` en `true`, llama a `await yuno.continuePayment()` para presentar las pantallas necesarias.

Los pagos con tarjeta que regresan `DECLINED` o `ERROR` también requieren llamar a `continuePayment` para ejecutar el reintento de pago (mantiene abierto el formulario de tarjeta mostrando el rechazo); si ninguno de esos casos aplica, llama a `unmountSdk` para limpiar. Consulta [Reintento de pago](https://docs.y.uno/es/docs/sdks/resources/references/web.md#payment-retry) para más detalles.

### Valor de retorno de `continuePayment` u null

Para los métodos de pago que requieren una acción del lado del comercio (p. ej., cuando el proveedor de pago requiere una URL de redirección en un webview), el método `await yuno.continuePayment()` devuelve un objeto con la siguiente estructura o null:

```typescript theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  action: 'REDIRECT_URL'
  type: string
  redirect: {
    init_url: string
    success_url: string
    error_url: string
  }
} | null
```

Cuando el método devuelve un objeto, puedes manejar los flujos de pago de tu aplicación que requieren un manejo de redirección personalizado. Cuando devuelve null, no se necesita ninguna acción adicional del lado del comercio.

### Funciones complementarias

Para estilos, temas, opciones del formulario y configuraciones adicionales, consulta [Personalizaciones del SDK](https://docs.y.uno/es/docs/sdks/resources/references/web.md). [Changelog](https://docs.y.uno/es/changelog/web.md#v1-3-0).

## Referencia común

Para ver todos los detalles de parámetros y personalización, consulta la [Referencia común del SDK Web](https://docs.y.uno/es/docs/sdks/resources/references/web.md).


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