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.
¿Debo usar el Seamless SDK Lite o el completo?Usa el Seamless SDK completo para el listado automático de métodos de pago y la visualización separada de los botones de pago (como PayPal). El Seamless SDK Lite te da más control sobre cómo se muestran y se organizan los métodos de pago.
Paso 1: incluye la biblioteca en tu proyecto
La guía de integración ofrece tres métodos flexibles:- Inclusión directa del script en 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: Autenticación
Paso 3: crea una sesión de checkout
Si tu flujo de trabajo requiere enviar el objeto
additional_data, puede enviarse como parte de la sesión de checkout.checkout_session con el endpoint Crear sesión de checkout.
- Primero, crea un cliente o recupera el ID de un cliente existente
- Inclúyelo al crear la
checkout_session
Para controlar la autorización y la captura con tarjetas, incluye
payment_method.detail.card.capture en la sesión de checkout: usa false para solo autorizar y true para capturar de inmediato.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 startSeamlessCheckout antes de mountSeamlessCheckout.Visualización de Google Pay y Apple PayDesde la versión 1.5 del SDK, Google Pay y Apple Pay aparecen como botones directos en lugar de botones de opción en la lista de métodos de pago. Se muestran por separado de los demás métodos de pago.
Paso 4: inicia el proceso de checkout
Usa la siguiente configuración para ofrecer a tus clientes una experiencia de pago fluida y fácil de usar:startSeamlessCheckout, especifica los callbacks para gestionar los pagos. También puedes personalizar la interfaz del checkout con los objetos texts.
El Seamless SDK crea el pago por sí mismo a partir de la sesión de checkout, por lo que no hay un callback createPayment ni una llamada a Create Payment desde tu servidor. Recibes el resultado en paymentResult, y tu servidor lo recibe mediante el webhook payment.purchase. El SDK también ejecuta el reintento de pago para las tarjetas rechazadas por sí solo, por lo que no necesitas llamar a continuePayment.
Parámetros
Configura el checkout seamless con las siguientes opciones:PromocionesLas promociones no se aplican cuando el SDK crea el pago por sí mismo (
mountSeamlessCheckout y mountSeamlessCheckoutLite): no solicita una cotización de promoción ni envía una línea de descuento. Para usar promociones en la web, integra con el checkout completo o Lite, donde tu servidor crea el pago.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.El paso a paso de esta página se refiere a una transacción iniciada por el cliente, sin la opción de recurrencia. Normalmente se usa en compras en línea de una sola vez, compras en tienda, retiros en cajeros automáticos, etc.
Paso 5: monta el SDK
Para presentar el proceso de checkout, usa la funciónawait yuno.mountSeamlessCheckout(). Este paso garantiza que el SDK se monte correctamente en el elemento HTML que elijas.
await yuno.startPayment(). Si omites esta llamada, el formulario de pago no se abrirá.
Paso 6: inicia el flujo de pago (obligatorio)
Llama aawait yuno.startPayment() inmediatamente después de await yuno.mountSeamlessCheckout() para abrir la interfaz del método de pago seleccionado:
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).
Monta botones externos
Puedes usar el métodomountExternalButtons 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.
Parámetros
Desmonta botones
Puedes desmontar un solo botón externo por tipo de método de pago:Desmonta el SDK
Para limpiar de forma explícita el Yuno SDK (por ejemplo, cuando un usuario cancela el flujo o necesitas quitar el SDK del DOM), usa el métodounmountSdk():
Revolut Pay
Hay dos formas de renderizar el botón de Revolut Pay:- Checkout completo: el botón aparece dentro de la lista de métodos de pago renderizada por el SDK.
- Botones externos (
mountExternalButtons): el comercio decide en qué contenedor de su página se monta el botón.
externalButtons.revolutPay dentro de startCheckout. A diferencia de otros botones, el widget lo renderiza el propio SDK de Revolut, por lo que la configuración corresponde directamente a las opciones de botón de Revolut.
Integración con botones externos
El comercio define un contenedor en su HTML y monta el botón allí:Requisitos de la sesión de checkout
Para que Revolut Pay funcione, la sesión de checkout que crea el comercio (de backend a backend) debe incluir estos campos. El SDK los lee de la sesión y no se configura nada en el frontend:amount.valueyamount.currency: obligatorios; se usan para crear la orden de Revolut que se muestra en el widget.callback_url: obligatorio; se usa como URL de redirección móvil para volver a la página del comercio (consulta Redirecciones móviles más abajo).
Configuración (externalButtons.revolutPay)
Toda la configuración es opcional. Revolut renderiza el botón, por lo que las opciones corresponden a los estilos oficiales de botón de Revolut:
Redirecciones móviles (callback_url)
En móvil, el flujo de Revolut puede saltar a la aplicación de Revolut (o a un navegador integrado) en lugar de quedarse en la ventana emergente. Para volver a la página del comercio, el SDK necesita URL de redirección. Las resuelve automáticamente a partir del callback_url que el comercio ya envía al crear la sesión de checkout (de backend a backend):
- El
callback_urlde la sesión se usa para los tres resultados:success,failureycancel. - No se necesita nada adicional en la configuración del SDK: si la sesión tiene un
callback_url, las redirecciones móviles funcionan; si no lo tiene, el flujo se queda solo en la web. - Cuando el comprador regresa desde la aplicación de Revolut, la URL incluye un parámetro de consulta
_rp_frque añade Revolut. Es inofensivo, pero los comercios que analizan estrictamente la URL de retorno deben tenerlo en cuenta.
Redirecciones en escritorio y en móvilEl SDK solo configura las URL de redirección móviles. Los flujos de escritorio siempre se resuelven dentro del widget o la ventana emergente, por lo que no ocurre ninguna redirección.
Flujo REDIRECT de PayPal
El Yuno SDK admite un flujoREDIRECT 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
REDIRECTomite la detección de fraude y la creación del OTT, y utiliza elorderIdproporcionado.
Inscripción de métodos de pago en el flujo seamless
Puedes inscribir métodos de pago (guardar tarjetas para uso futuro) directamente durante el flujo de pago seamless, definiendopayment_method.vault_on_success = true en la creación de la sesión de checkout.
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 realizará ningún almacenamiento seguro
- La respuesta del pago incluirá un
vaulted_tokenque puedes usar para transacciones futuras
Requisitos para el almacenamiento seguroPara 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 de nuestro lado, por lo que no se realizará ningún almacenamiento seguro.Manejo de errores
Gestiona en tu aplicación los errores que devuelve el SDK, como pagos fallidos o errores de validación. Para los códigos de estado HTTP y de respuesta, consulta Estados y códigos de respuesta en la referencia de la API.Reintento de pago
Cuando un pago con tarjeta devuelveDECLINED o ERROR, el reintento de pago mantiene abierto el formulario de tarjeta para que el comprador pueda corregir sus datos y volver a intentarlo sin reiniciar el checkout. Está deshabilitado por defecto y Yuno lo habilita por organización a solicitud. Es un indicador del lado del servidor, no una configuración del Dashboard ni del Checkout Builder.
En el flujo seamless esto es automático: el SDK mantiene abierto el formulario y gestiona el reintento por ti. En los flujos de Full Checkout, Lite y Secure Fields debes llamar a continuePayment en un pago con tarjeta rechazado o con error para activarlo. Consulta Reintento de pago en la referencia Web para más detalles.