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.
Sigue esta guía paso a paso para implementar y habilitar la capacidad de inscripción del Lite Web SDK de Yuno en tu app.

Paso 1: Incluye la biblioteca en tu proyecto

Antes de continuar con la implementación del Lite SDK, consulta la Guía de inicio rápido 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 capacidad de inscripción lite.
Biblioteca de TypeScriptSi usas TypeScript, Yuno ofrece una biblioteca que da acceso a todos los métodos disponibles en el Yuno Web SDK.

Paso 2: Inicializa el SDK con la clave pública

Inicializa el Yuno SDK en tu aplicación JavaScript 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. Usa el endpoint Crear cliente para crear nuevos clientes. En la respuesta recibirás el id del cliente, que usas 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 Crear sesión de cliente. El customer_session se proporcionará en la respuesta. Necesitas un nuevo customer_session cada vez que inscribas un nuevo método de pago.

Paso 4: Inicia el proceso de inscripción

Usa la siguiente configuración para ofrecer a tus clientes una experiencia de inscripción ligera y fácil de usar:
Al usar mountEnrollmentLite, especifica los callbacks que gestionarán la inscripción. También puedes personalizar la interfaz con los objetos texts.

Parámetros

Configura la inscripción lite con las siguientes opciones:
Valores de estadoLos valores de estado comunes incluyen ENROLLED, DECLINED, CANCELED y ERROR.

Inscripción en PayPal con el modo de renderizado element

Disponible desde el Web SDK 1.10.13.
De forma predeterminada, mountEnrollmentLite abre el modal de Yuno para la inscripción en PayPal. El comprador hace clic en tu botón de PayPal, ve el modal y tiene que hacer clic en PayPal por segunda vez. Con el modo de renderizado element, el botón de PayPal se renderiza directamente en tu página y el comprador completa la inscripción con un solo clic.

Cómo funciona

Agrega un contenedor vacío a tu página y luego pasa renderMode: { type: 'element', elementSelector } a mountEnrollmentLite. El SDK renderiza el botón real de PayPal dentro de ese contenedor y muestra un esqueleto de carga hasta que PayPal termina de cargar. El botón de PayPal reemplaza tu propio botón: no coloques tu botón delante de él. Si no pasas renderMode, el comportamiento del modal se mantiene exactamente como antes.

Pasos de integración

  1. Elimina tu botón de PayPal actual.
  2. Agrega un <div> vacío donde debe aparecer el botón de PayPal.
  3. Pasa renderMode con type: 'element' y un elementSelector que apunte a ese <div>.
El botón ocupa el 100% del ancho del contenedor, a menos que definas width.

Personalizar el botón de PayPal

Opcional. Pasa externalButtons.paypal a mountEnrollmentLite para darle estilo al botón, con las mismas propiedades que el botón express de PayPal en el checkout. Los valores predeterminados difieren de los del checkout, por lo que se listan completos a continuación.

Resultado

  • El comprador hace clic en el botón de PayPal, aprueba en la ventana emergente de PayPal y el SDK completa la inscripción.
  • enrollmentStatus recibe el vaultedToken con el estado ENROLLED.
  • Si el comprador cierra la ventana emergente, error recibe CANCELED_BY_USER.

Inscripción con KCP KakaoPay y PAYCO (Web)

La inscripción de KakaoPay en escritorio y las redirecciones POST de KCP en móvil están disponibles desde el Web SDK 1.11.27. La inscripción de PAYCO en escritorio es compatible desde el Web SDK 1.11.43.
El Yuno Lite Web SDK es compatible con la inscripción de KakaoPay (KAKAO_PAY) y PAYCO (KCP_PAYCO) mediante KCP en navegadores de escritorio, así como con redirecciones automáticas de formulario HTTP POST para la inscripción con KCP en navegadores móviles.

Flujo de inscripción en escritorio

En navegadores de escritorio, las inscripciones de KakaoPay y PAYCO renderizan un botón de acción dentro del componente de inscripción lite.

Cómo funciona

  1. Carga del script y configuración del callback: Cuando se monta el componente de inscripción, el SDK declara el manejador de callback de KCP (window.m_Completepayment) y luego verifica y carga el paquete de scripts de KCP desde script_url (https://*.kcp.co.kr).
  2. Acción del usuario: El comprador hace clic en el botón de acción. El SDK prepara el formulario del pedido y abre la ventana de autorización de KCP (KCP_Pay_Execute_Web).
  3. Finalización y envío: Cuando el comprador termina en KCP, KCP llama al callback del SDK con el resultado (res_cd, res_msg, enc_data, enc_info, tran_cd), y el SDK lo envía por POST al result_url del backend (https://*.y.uno o el host de tu API white-label) mediante el envío de un formulario oculto. Cuando se configura con RENDER_POPUP, el envío POST se realiza dentro de la ventana emergente en lugar de navegar en la página principal.
  4. Limpieza: Al desmontar el componente de inscripción, se cierra cualquier ventana de KCP abierta y se restaura cualquier manejador window.m_Completepayment preexistente.

Estados del botón y recuperación de errores

  • Botón deshabilitado: Si falta la configuración de inscripción requerida del backend (script_url, form_fields o result_url) o apunta a un host no autorizado, el botón se deshabilita y muestra un mensaje de error en línea.
  • Reintento de carga del script: Si los scripts de KCP no se cargan, el botón muestra un error en línea; al hacer clic en él se vuelve a cargar KCP y, una vez cargado, el siguiente clic abre KCP.
  • Recuperación tras cerrar la ventana emergente: Si el comprador cierra la ventana emergente de KCP sin aprobar, el SDK detecta la eliminación de la capa mediante observadores de mutaciones del DOM y vuelve a habilitar el botón para otro intento.
  • Recuperación por tiempo de espera: Si el navegador permanece en la página 10 segundos después de enviar el resultado de la inscripción (normalmente porque faltan políticas CSP form-action y se bloquea el envío del formulario), el SDK borra el estado de procesamiento, muestra un error en línea y vuelve a habilitar el botón para que el comprador pueda reintentar. Ten en cuenta que no se dispara ningún callback de error del comercio.

Redirección POST de KCP en móvil

Al inscribirse con KCP en navegadores móviles, el backend devuelve un payload require_action.redirect con method: "POST" y un init_url que apunta a un host de KCP (*.kcp.co.kr). El Lite Web SDK detecta automáticamente la configuración de redirección POST, construye un formulario oculto con los form_fields, lo agrega al DOM y lo envía para llevar al usuario directamente al proveedor.

Requisitos de Content Security Policy (CSP)

Si tu sitio web aplica una Content Security Policy (CSP) estricta, configura las siguientes directivas para permitir los scripts de KCP, las superposiciones con iframe y los envíos de formularios:
Si faltan las directivas form-action para *.y.uno o *.kcp.co.kr, el navegador bloqueará el envío del formulario sin errores de JavaScript, lo que provocará que la inscripción agote el tiempo de espera.

Paso 5: Inicia la inscripción (obligatorio)

Después de montar el SDK con await yuno.mountEnrollmentLite(), el formulario se mostrará en el elemento especificado. El usuario podrá entonces ingresar los datos de su método de pago para completar la inscripción.
App de demostraciónAdemás de los ejemplos de código proporcionados, puedes acceder a la app de demostración para ver una implementación completa de los SDK de Yuno (clónala desde el repositorio).

Manejo de errores

Gestiona en tu app los errores que devuelve el SDK, como inscripciones fallidas 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 changelog para ver las últimas actualizaciones del SDK y el historial de versiones.