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.
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:- Inclusión directa del script HTML
- Inyección dinámica de JavaScript
- Instalación del módulo NPM
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 unaPUBLIC_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 elcustomer_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: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.
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 pasarenderMode: { 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
- Elimina tu botón de PayPal actual.
- Agrega un
<div>vacío donde debe aparecer el botón de PayPal. - Pasa
renderModecontype: 'element'y unelementSelectorque apunte a ese<div>.
width.
Personalizar el botón de PayPal
Opcional. PasaexternalButtons.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.
enrollmentStatusrecibe elvaultedTokencon el estadoENROLLED.- Si el comprador cierra la ventana emergente,
errorrecibeCANCELED_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.
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
- 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 desdescript_url(https://*.kcp.co.kr). - 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). - 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 alresult_urldel backend (https://*.y.unoo el host de tu API white-label) mediante el envío de un formulario oculto. Cuando se configura conRENDER_POPUP, el envío POST se realiza dentro de la ventana emergente en lugar de navegar en la página principal. - Limpieza: Al desmontar el componente de inscripción, se cierra cualquier ventana de KCP abierta y se restaura cualquier manejador
window.m_Completepaymentpreexistente.
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_fieldsoresult_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 payloadrequire_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:Paso 5: Inicia la inscripción (obligatorio)
Después de montar el SDK conawait 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).