Skip to main content
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.
El SDK Web facilita integrar flujos de pago en tus experiencias web y basadas en navegador.

Recursos adicionales

Requisitos

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)
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.
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.
Opción 2: etiqueta script de HTML
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.
Opción 3: JavaScript dinámico
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.

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 más arriba.

Paso 2: inicializa el SDK

Después de incluir la biblioteca (paso 1), inicializa el SDK. Consulta la Guía de inicio rápido 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 para ver todas las opciones. Para estilos, temas y configuraciones adicionales, consulta Personalizaciones del SDK.
Por defecto, el SDK de Yuno se renderiza como un modal. Puedes especificar el elemento donde se renderizará el SDK. Consulta Modo de renderizado 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:

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:

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.
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), 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):
Cuando una promoción 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. 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. 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. 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 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:
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. Changelog.

Referencia común

Para ver todos los detalles de parámetros y personalización, consulta la Referencia común del SDK Web.