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.
El Yuno Web SDK es un script de navegador. En React, lo cargas una sola vez, montas el checkout dentro de un componente que solo se ejecuta en el navegador y lo desmontas cuando el componente desaparece. Esta página muestra ese patrón para Seamless SDK, Lite SDK y Secure Fields, además de los detalles específicos de Next.js para el App Router y el Pages Router. Todo lo que aparece aquí usa los mismos métodos documentados para JavaScript sin frameworks. Consulta Seamless SDK (Web), Lite SDK (Web), Secure Fields y la Web Reference para ver cada parámetro.

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).
loadScript() solo empieza a descargar el SDK cuando tu app lo llama, lo que en una app de React ocurre después de que se ejecuta tu bundle. Agrega un preload para main.js y preconnects a los hosts de Yuno en el <head> de tu HTML para que la descarga comience mientras la página carga. Consulta Preload the SDK script.
Si prefieres la etiqueta script, agrégala a tu HTML y llama a Yuno.initialize desde el navegador:
Ambas opciones usan window, por lo que deben ejecutarse en el navegador. Nunca importes @yuno-payments/sdk-web ni llames a Yuno.initialize desde un server component, getServerSideProps o una server action. Las secciones siguientes muestran dónde colocar cada llamada.

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.
Consulta Create Checkout Session para ver cada campo.

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.
Si el script no se carga, la promesa en caché se borra para que el siguiente montaje lo intente de nuevo en lugar de reutilizar el fallo.

Seamless SDK en un componente

Monta dentro de useEffect, 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.
Aquí importan tres detalles:
  • Dependencias: solo yuno, checkoutSession y countryCode vuelven a montar el formulario. Los callbacks pasan por un ref para que los nuevos renderizados del componente padre no desmonten el checkout.
  • Limpieza: unmountSdk elimina el SDK del DOM. Si el componente se desmonta mientras mountSeamlessCheckout todavía se está ejecutando, la comprobación cancelled lo desmonta en cuanto termina, de modo que no queda ningún formulario en un elemento desvinculado.
  • Apertura del formulario: startPayment abre el método de pago seleccionado. Llámalo desde tu botón de pago como se muestra, o justo después de que mountSeamlessCheckout se resuelva. Si nunca lo llamas, el formulario no se abre.
Cuando el comprador necesite una nueva sesión después de un pago fallido, llama a yuno.updateCheckoutSession(newSession) en lugar de volver a montar. Si la nueva sesión cambia los métodos de pago, los estilos o el país, vuelve a montar cambiando la prop checkoutSession. Consulta updateCheckoutSession.

Lite SDK en un componente

Lite SDK renderiza un método de pago por llamada. El patrón de React es el mismo, con startCheckout 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.
Una tarjeta rechazada o fallida va a 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 de app/ 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.
Si prefieres mantener el componente fuera del bundle del servidor por completo, cárgalo con next/dynamic y ssr: false:

Pages Router

Crea la sesión en getServerSideProps 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-height cercano 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 loadScript en 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.js y 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.