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 pago del Lite Web SDK de Yuno en tu app.

Paso 1: incluye la biblioteca en tu proyecto

Equivalente en el nuevo SDK para los pasos 1 y 2: Instalar. La guía de integración ofrece tres métodos flexibles:
  1. Inclusión directa del script en 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 funcionalidad 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 checkout

Equivalente en el nuevo SDK: Crear la sesión de checkout. Para iniciar el flujo de pago, crea una nueva checkout_session con el endpoint Crear sesión de checkout.
  • Primero, crea un cliente u obtén el ID de un cliente existente
  • Inclúyelo al crear la checkout_session
Controla la autorización y la capturaPara controlar la autorización y la captura con tarjetas, envía payment_method.detail.card.capture en la solicitud Crear pago que tu backend envía desde createPayment: usa false para solo autorizar y true para capturar de inmediato. Yuno lee este campo de la solicitud de pago. Consulta Flujo de cancelación y captura.

Parámetros clave

Evento onPaymentMethodSelectPara todos los APM, incluidos Google Pay, Apple Pay y PayPal, onPaymentMethodSelected se activa en cuanto 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.mountCheckoutLite().

Paso 4: inicia el proceso de checkout

Equivalente en el nuevo SDK para los pasos 4 a 6: Migración del modo Lite. Usa la siguiente configuración para ofrecer a tus clientes una experiencia de pago ligera y fácil de usar:
Al usar startCheckout, especifica los callbacks para gestionar los pagos. También puedes personalizar la interfaz del checkout con los objetos texts.

Parámetros

Configura el checkout Lite con las siguientes opciones:
PromocionesCuando las Promociones están habilitadas para tu organización, el checkout Lite solicita una cotización de promoción mientras el comprador escribe la tarjeta, y createPayment la recibe en tokenWithInformation.quote. Las wallets no son un destino compatible en esta versión: mountExternalButtons no solicita una cotización. Consulta Promociones.
Transacciones iniciadas por el cliente y por el comercioLos pagos pueden ser iniciados por el cliente (CIT) o por el comercio (MIT). Encuentras más información sobre sus características en Credenciales almacenadas.

Paso 5: monta el SDK

Para presentar el proceso de checkout según el método de pago seleccionado, usa la función await yuno.mountCheckoutLite(). Este paso garantiza que el SDK se monte correctamente en el elemento HTML que elijas.
Consulta la página Tipo de pago para ver la lista completa de tipos de método de pago que puedes usar al montar el SDK. El vaultedToken es opcional. Representa un método de pago inscrito previamente. Si proporcionas el vaultedToken, no se le pedirá al usuario que ingrese de nuevo la información de pago, ya que la proporcionó en una transacción anterior. Después de montar, debes iniciar el flujo de checkout llamando a yuno.startPayment(). Si omites esta llamada, el formulario de pago no se abrirá. Ten en cuenta que yuno.startPayment() también devuelve una promesa y debes esperarla con await.

Paso 6: inicia el flujo de pago (obligatorio)

Llama a await yuno.startPayment() inmediatamente después de await yuno.mountCheckoutLite() para abrir la interfaz del método de pago seleccionado:
También puedes iniciarlo desde una acción del usuario, como hacer clic en un botón:
App de demostraciónAdemás de los ejemplos de código, puedes acceder a la App de demostración para ver una implementación completa de los SDK de Yuno (clónala desde el repositorio).

Verifica que un método de pago se mostrará antes de listarlo

Si dibujas tu propia lista de métodos de pago, pregunta al SDK qué métodos se mostrarán realmente para este comprador y esta sesión de checkout antes de mostrarlos. Llama a isPaymentMethodAvailable después de startCheckout y oculta todos los métodos que se resuelvan en false. De lo contrario, el comprador puede elegir un método que no está habilitado para la sesión, o una wallet que el dispositivo no puede usar, y ver un recuadro vacío donde debería estar el formulario o el botón.
La respuesta es la misma decisión que toma el SDK al renderizar ese método, y el método nunca rechaza. Consulta isPaymentMethodAvailable para ver qué se verifica en cada método.

Monta botones externos

Puedes usar el método mountExternalButtons para renderizar los botones de Google Pay y Apple Pay en ubicaciones personalizadas de tu interfaz. Esto te da control sobre dónde se muestran estos botones. Llámalo después de startCheckout.
Un botón de wallet se renderiza solo cuando el método de pago está habilitado para la sesión de checkout y supera la verificación de dispositivo y navegador del SDK, por ejemplo isReadyToPay() de Google Pay para la configuración de la sesión. Por lo tanto, el mismo código puede mostrar un botón de wallet en un dispositivo o navegador y no en otro. En el Web SDK 1.11.43 y posteriores, o 1.10.35 y posteriores, llama a isPaymentMethodAvailable para cada wallet antes de montarla, y muestra solo los contenedores de las wallets que se resuelvan en true.

Parámetros de los botones externos

Desmontar botones

Puedes desmontar un solo botón externo según el tipo de método de pago:
O desmontar todos los botones externos a la vez:

Desmontar el SDK

Para una limpieza explícita del Yuno SDK, por ejemplo cuando un usuario cancela el flujo o necesitas quitar el SDK del DOM, usa el método unmountSdk():

Flujo REDIRECT de PayPal

El Yuno SDK admite un flujo REDIRECT para PayPal. Este flujo es útil cuando PayPal no se inicializó al comienzo del SDK o cuando se usa un orderId de PayPal preexistente.
  • PaypalButtonModal: si PayPal no está inicializado, el SDK puede renderizar el botón de PayPal dentro de un modal.
  • Flujo: el flujo REDIRECT omite la detección de fraude y la creación del OTT, y utiliza el orderId proporcionado.

Inscripción de métodos de pago en el flujo Lite

Equivalente en el nuevo SDK: Inscripción. Puedes inscribir métodos de pago (guardar tarjetas para uso futuro) directamente durante el flujo de pago Lite configurando payment_method.vault_on_success = true en la solicitud Crear pago que tu backend envía desde createPayment, anidado bajo payment_method, como se muestra a continuación. En el flujo Lite tu servidor crea el pago, por lo que este es el lugar donde va el indicador; configurarlo en la sesión de checkout es el patrón Seamless, donde el SDK crea el pago. Cuando vault_on_success se establece en true:
  • El método de pago se inscribirá automáticamente si el estado del pago es SUCCEEDED
  • Si el pago no es exitoso, no se guardará el método de pago
  • La respuesta del pago incluirá un vaulted_token que puedes usar en transacciones futuras
Ejemplo (extracto parcial: solo se muestran los campos relevantes):
Requisitos para guardar el método de pagoPara generar y recibir un vaulted_token cuando vault_on_success = true, el pago debe hacer referencia a un cliente existente de Yuno mediante customer_payer.id en la sesión de checkout. Crear o enviar los datos del cliente en línea dentro de la solicitud de pago no crea al cliente en el sistema de Yuno, por lo que no se guardará el método de pago.
Para obtener más información sobre la inscripción de métodos de pago, consulta Inscribir métodos de pago.

Manejo de errores

Equivalente en el nuevo SDK: el controlador onStatus. Gestiona en tu app los errores que devuelve el SDK, como pagos fallidos o errores de validación. Para los códigos de estado y de respuesta HTTP, 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.