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

# Headless SDK (Inscripción Web)

> Inscribe métodos de pago con el Headless SDK en Web y genera un vaulted token para los datos de la tarjeta

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

> [!WARNING]
>
> **Orientación: elige tu flujo de integración**. Antes de comenzar, revisa el [flujo de integración oficial](https://docs.y.uno/docs/sdks/overview/understanding-flows.md).
>
> * **Flujo estándar ([Full Checkout](https://docs.y.uno/docs/sdks/full-checkout/web-payments))**: Recomendado para la mayoría de los comercios. Yuno se encarga de la interfaz, la seguridad y las actualizaciones automáticas de los métodos de pago.
> * **Flujo personalizado (este SDK)**: Úsalo solo si necesitas control total sobre la experiencia de usuario. **Nota**: Serás responsable de gestionar manualmente los estados de los pagos, las transiciones de 3DS y la recopilación de datos para el enrutamiento de fraude.

El Headless SDK de Yuno te permite inscribir métodos de pago y tokenizar tarjetas para guardarlas y usarlas en el futuro.

Los siguientes pasos describen cómo inscribir un método de pago con el Headless SDK de Yuno.

## Requisitos

Para ejecutar el proceso de inscripción, debes proporcionar el `customer_session` para iniciarlo en el [Paso 3](#step-3-create-a-customer-session). Para obtener el `customer_session`, debes:

1. **Crear un cliente**: se requiere un cliente para inscribir pagos. Usa el endpoint [Create Customer](https://docs.y.uno/reference/customers/create-customer.md) para crear nuevos clientes. En la respuesta recibirás el `id` del cliente, que usarás para crear la sesión de cliente.
2. **Crear la sesión de cliente**: usa el `id` del cliente y el endpoint [Create Customer Session](https://docs.y.uno/reference/customer-sessions-enrollment/create-customer-session.md) para recibir el `customer_session`.

## Paso 1: incluye la biblioteca en tu proyecto

Antes de continuar con la implementación del Headless SDK, consulta la [Descripción general de la integración del SDK](https://docs.y.uno/es/docs/sdks/overview/quickstart.md) para ver las instrucciones detalladas sobre cómo integrar correctamente el SDK en tu proyecto.

La guía de integración ofrece tres métodos flexibles:

1. Inclusión directa del script HTML
2. Inyección dinámica de JavaScript
3. Instalación del módulo NPM

Elige el método de integración que mejor se adapte a tu flujo de desarrollo y a tus requisitos técnicos. Después de completar la integración del SDK, puedes continuar con los siguientes pasos para implementar la inscripción headless.

> [!NOTE]
>
> **Biblioteca de TypeScript**
>
> Si usas TypeScript, Yuno ofrece una [biblioteca](https://www.npmjs.com/package/@yuno-payments/sdk-web-types) que puedes usar para ver todos los métodos disponibles en el Yuno Web SDK.

## Paso 2: inicializa el Headless SDK con la clave pública

En tu aplicación JavaScript, crea una instancia de la clase `Yuno` proporcionando una `PUBLIC_API_KEY` válida.

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

> [!NOTE]
>
> **Credenciales**
>
> Consulta la página de credenciales para obtener más información: [/reference/getting-started/authentication](https://docs.y.uno/es/reference/getting-started/authentication.md)

## Paso 3: crea una sesión de cliente

Para iniciar el proceso de inscripción, debes proporcionar el `customer_session`. Primero, debes crear un cliente. Necesitas un cliente con el que inscribir pagos. Usa el endpoint [Create Customer](https://docs.y.uno/reference/customers/create-customer.md) para crear nuevos clientes. En la respuesta recibirás el `id` del cliente, que usarás para crear la sesión de cliente.

Después de crear el cliente, puedes crear la sesión de cliente. Usa el `id` del cliente y el endpoint [Create Customer Session](https://docs.y.uno/reference/customer-sessions-enrollment/create-customer-session.md). El `customer_session` se entregará en la respuesta. Necesitas un nuevo `customer_session` cada vez que inscribas un nuevo método de pago.

## Paso 4: crea un objeto de método de pago de inscripción

Necesitas un objeto de método de pago de inscripción para configurar la integración del Headless SDK para la inscripción. Puedes crearlo con el endpoint [Enroll Payment Method](https://docs.y.uno/reference/payment-methods-checkout/enroll-payment-method-checkout.md). Al crear el objeto de método de pago, debes definir en qué método de pago puede inscribirse tu cliente. Actualmente, solo CARD está disponible para el Headless SDK.

> [!WARNING]
>
> **Verificar tarjeta**
>
> Si quieres verificar las tarjetas (autorización de valor cero) antes de la inscripción, debes proporcionar el objeto `verify`. Inclúyelo al crear el objeto de método de pago para la sesión de cliente.

## Paso 5: inicia el proceso de inscripción

A continuación, iniciarás el proceso de inscripción con la función `apiClientEnroll`, proporcionando los parámetros de configuración necesarios.

### Parámetros

Configura la inscripción con las siguientes opciones:

| Parámetro | Descripción |
| - | - |
| `country_code` | Este parámetro especifica el país para el cual se configura el proceso de pago. Usa un valor `ENUM` que represente el código de país deseado. Puedes encontrar la lista completa de países compatibles y sus códigos correspondientes en la página [Country Coverage](https://docs.y.uno/es/docs/sdks/resources/country-coverage.md). |
| `customer_session` | Se refiere a la [sesión de cliente](https://docs.y.uno/es/docs/basic-concepts/sessions.md) de la inscripción actual, recibida como respuesta del endpoint [Create Customer Session](https://docs.y.uno/reference/customer-sessions-enrollment/create-customer-session.md). Ejemplo: `'438413b7-4921-41e4-b8f3-28a5a0141638'` |

```javascript theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
const apiClientEnroll = await yuno.apiClientEnroll({
  country_code: "CO",
  customer_session: "eec6578e-ac2f-40a0-8065-25b5957f6dd3"
});
```

## Paso 6: genera un vaulted token

Después de recopilar toda la información del usuario, puedes iniciar la inscripción. Primero, debes crear un `vaulted_token` con la función `apiClientEnroll.continueEnrollment`. Como es una función asíncrona, puedes usar `try/catch` para asegurarte de manejar correctamente los errores que se produzcan. El siguiente ejemplo muestra cómo crear un `vaulted_token`:

```javascript theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
const vaultedTokenResponse = await apiClientEnroll.continueEnrollment({
  customer_session: "eec6578e-ac2f-40a0-8065-25b5957f6dd3",
  payment_method: {
    type: "CARD",
    card: {
      detail: {
        expiration_month: 11,
        expiration_year: 25,
        number: "4111111111111111",
        security_code: "123",
        holder_name: "ANDREA B",
        type: "CREDIT"
      }
    },
    customer: {
    }
  }
});
```

`card.detail.type` es opcional. Si lo omites, Yuno detecta el tipo de tarjeta a partir del número de tarjeta. Si lo envías, se guarda con la tarjeta y se usa en pagos posteriores, por lo que un tipo incorrecto puede causar rechazos.

Después de inscribir la nueva tarjeta, recibirás el `vaulted_token`. Puedes usarlo para realizar pagos en el futuro sin pedir los datos de la tarjeta de tu cliente. El siguiente bloque de código muestra un ejemplo de respuesta de la función `apiClientEnroll.continueEnrollment`:

```json theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
 "vaulted_token": "9104911d-5df9-429e-8488-ad41abea1a4b",
 "customer": {
   "session": "eec6578e-ac2f-40a0-8065-25b5957f6dd3"
 },
 "status": "ENROLLED"
}
```

> [!NOTE]
>
> **Valores de estado posibles**
>
> El campo `status` puede tener uno de los siguientes valores:
>
> * `CREATED`
> * `EXPIRED`
> * `REJECTED`
> * `READY_TO_ENROLL`
> * `ENROLL_IN_PROCESS`
> * `UNENROLL_IN_PROCESS`
> * `IN_PROCESS`
> * `ENROLLED`
> * `DECLINED`
> * `CANCELED`
> * `ERROR`
> * `UNENROLLED`

> [!NOTE]
>
> **Aplicación de demostración**
>
> Además de los ejemplos de código proporcionados, puedes acceder a la [Demo App](https://github.com/yuno-payments/yuno-sdk-web) para ver una implementación completa de los SDK de Yuno (clona el repositorio).

## Manejo de errores

Maneja en tu aplicación los errores devueltos por el SDK, como fallos de inscripción o errores de validación. Para los códigos de estado HTTP y de respuesta, consulta [Códigos de estado y de respuesta](https://docs.y.uno/es/reference/getting-started/response-codes.md) en la referencia de la API.

## Mantente al día

Visita el [registro de cambios](https://docs.y.uno/changelog/web.md#v1-6-0) para ver las últimas actualizaciones del SDK y el historial de versiones.


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