Saltar al contenido principal
Esta página documenta un SDK heredado. ¿Vas a iniciar una nueva integración? Usa el Yuno SDK. ¿Ya usas un SDK heredado? Sigue la guía de migración.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.
Orientación: elige tu flujo de integración. Antes de comenzar, revisa el flujo de integración oficial.
  • Flujo estándar (Full Checkout): 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. Para obtener el customer_session, debes:
  1. Crear un cliente: se requiere un cliente para inscribir pagos. Usa el endpoint Create Customer 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 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 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.
Biblioteca de TypeScriptSi usas TypeScript, Yuno ofrece una biblioteca 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.
CredencialesConsulta la página de credenciales para obtener más información: /reference/getting-started/authentication

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 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. 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. 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.
Verificar tarjetaSi 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:

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:
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:
Valores de estado posiblesEl 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
Aplicación de demostraciónAdemás de los ejemplos de código proporcionados, puedes acceder a la Demo App 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 en la referencia de la API.

Mantente al día

Visita el registro de cambios para ver las últimas actualizaciones del SDK y el historial de versiones.