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.
Elige la integración
Instalación
Instala el paquete de NPM y, opcionalmente, las definiciones de TypeScript:loadScript inyecta el script del SDK y se resuelve con el objeto Yuno. La inicialización es un segundo paso: llama a Yuno.initialize con tu clave de API pública para obtener la instancia con la que montas. Configura sri: true para que el navegador verifique el script contra su hash publicado (consulta Subresource Integrity).
Yuno.initialize desde el navegador:
Crea la sesión de checkout en tu servidor
El SDK necesita una sesión de checkout, y crearla requiere tu clave privada. Créala en tu servidor y pasa el ID al componente como prop. La sesión expira a las 2.5 horas en producción, así que créala cuando el comprador llegue al paso de pago, no durante la compilación de la página.Carga el SDK una sola vez
Un hook pequeño mantiene una instancia del SDK por página y la comparte entre componentes. La promesa se guarda en caché a nivel de módulo para que React StrictMode, que ejecuta los efectos dos veces en desarrollo, no inyecte el script dos veces.Seamless SDK en un componente
Monta dentro deuseEffect, guarda los callbacks en un ref para que un nuevo renderizado no vuelva a montar el formulario, y llama a unmountSdk en la limpieza. elementSelector es el elemento en el que se monta el checkout y es obligatorio. Usa renderMode.type: 'element' para que los formularios del método de pago y de las acciones también se rendericen dentro de elementos que te pertenecen.
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. También ejecuta por su cuenta el reintento de pago para las tarjetas rechazadas. Obtienes el resultado en paymentResult, y tu servidor lo recibe mediante el webhook payment.purchase.
- Dependencias: solo
yuno,checkoutSessionycountryCodevuelven a montar el formulario. Los callbacks pasan por un ref para que los nuevos renderizados del componente padre no desmonten el checkout. - Limpieza:
unmountSdkelimina el SDK del DOM. Si el componente se desmonta mientrasmountSeamlessCheckouttodavía se está ejecutando, la comprobacióncancelledlo desmonta en cuanto termina, de modo que no queda ningún formulario en un elemento desvinculado. - Apertura del formulario:
startPaymentabre el método de pago seleccionado. Llámalo desde tu botón de pago como se muestra, o justo después de quemountSeamlessCheckoutse resuelva. Si nunca lo llamas, el formulario no se abre.
Lite SDK en un componente
Lite SDK renderiza un método de pago por llamada. El patrón de React es el mismo, constartCheckout y mountCheckoutLite en lugar de los métodos de Seamless. Los botones express se montan por separado con mountExternalButtons.
A diferencia de Seamless, Lite te entrega un token de un solo uso en createPayment y tu servidor crea el pago. Tu ruta /api/payments llama a Create Payment con payment_method.token y checkout.session, y luego el callback sigue las reglas de reintento de pago: continuePayment para una tarjeta rechazada o cuando sdk_action_required es true, y unmountSdk en cualquier otro caso.
Secure Fields en un formulario que te pertenece
Secure Fields te ofrece tres campos seguros para PCI (pan, expiration, cvv) que se renderizan en elementos de tu formulario. yuno.secureFields es asíncrono, así que usa await dentro del efecto, luego crea los campos y genera el token de un solo uso al enviar el formulario.
unmountSdk no elimina los Secure Fields. Conserva cada campo y llama a su unmountSync en la limpieza; de lo contrario, los campos de la tarjeta permanecen en la página y StrictMode los renderiza dos veces en desarrollo.
continuePayment para que el reintento de pago pueda mantener el formulario abierto mostrando el rechazo. Cualquier otro caso que no requiera más acciones va a mountStatusPayment.
Configura checkoutSession en secureFields({ ... }) y no en generateTokenWithInformation; la lógica del reintento de pago depende de ello.
Next.js
App Router
Los componentes dentro deapp/ son server components por defecto. Coloca cada llamada al SDK en un archivo que comience con 'use client', y crea la sesión en una server action o en un route handler.
next/dynamic y ssr: false:
Pages Router
Crea la sesión engetServerSideProps y renderiza el componente de cliente. El hook useEffect solo se ejecuta en el navegador, así que el componente anterior funciona sin cambios.
Variables de entorno
La clave secreta privada nunca debe tener el prefijo
NEXT_PUBLIC_.
Reduce el desplazamiento del diseño
El checkout se carga después de que la página se renderiza. Reserva el espacio que ocupará para que la página no salte:- Dale al elemento de montaje un
min-heightcercano a la altura final del formulario. - Mantén
showLoading: true(el valor por defecto) para que el SDK muestre su propio indicador de carga mientras obtiene tus métodos de pago. - Llama a
loadScripten la página anterior al paso de pago si puedes, para que el script ya esté en caché cuando llegue el comprador. Carga el mismo archivo en todas las páginas, así que el navegador lo descarga una sola vez. - Haz preload de
main.jsy preconnect a los hosts de Yuno desde el<head>del HTML para que la descarga no espere a tu bundle. Consulta Preload the SDK script.
Solución de problemas
Próximos pasos
Migrar desde Stripe Elements
Relaciona cada concepto de Elements con su equivalente en Yuno.
Web Reference
Cada parámetro, callback y método de ciclo de vida del Web SDK.