Saltar al contenido principal
La mayoría de las tiendas integran Yuno mediante el flujo estándar del plugin descrito en Configura Yuno en VTEX. Para las tiendas que necesitan renderizar la experiencia de checkout de Yuno directamente en su propio front-end, Yuno ofrece el paquete npm Yuno SDK Web for VTEX.

Cuándo aplica

Si tu tienda tiene requisitos estándar, no necesitas esta página. El flujo estándar del plugin ya se encarga de todo. Usa la integración del Headless SDK solo cuando tu tienda tenga necesidades específicas que requieran que tu front-end renderice directamente la experiencia de checkout de Yuno. Esto aplica, por ejemplo, a los checkouts headless o muy personalizados. Una tienda headless en VTEX es aquella en la que el comercio ejecuta su propio front-end fuera de la tienda nativa de VTEX. Sigue usando las capacidades de comercio de VTEX (catálogo, carrito, checkout, órdenes) a través de APIs. Como el front-end está completamente bajo tu control, el plugin estándar ya no renderiza la experiencia de checkout de Yuno por ti. En su lugar, tu front-end monta el Yuno SDK Web for VTEX por sí mismo. Para conocer los antecedentes de esta arquitectura, consulta la guía de Headless commerce de VTEX.

Qué se mantiene igual

La configuración en tu VTEX dashboard y en tu Yuno dashboard no cambia:
  • Sigues configurando Yuno como proveedor de pago en VTEX.
  • Sigues configurando el webhook en tu Yuno dashboard.
  • El Yuno Payment Connector sigue siendo la base de la integración. Todos los pagos continúan fluyendo a través de él.
  • Los tokens de red para compradores recurrentes funcionan de la misma manera aquí: los campos Enable Network Tokens y Create Customer están en la misma configuración del proveedor, y todo pago con tarjeta procesado a través del Connector es elegible, sin importar qué flujo renderizó el checkout.

Qué es diferente

En lugar de dejar que el flujo estándar renderice el checkout de Yuno por ti, tu front-end monta directamente el Yuno SDK Web for VTEX y le proporciona la configuración que necesita para renderizar la experiencia de checkout para el comprador actual.

Antes de montar: ejecuta primero la autorización

El SDK no genera su propio contexto de pago. Renderiza el checkout a partir de un payload producido por el Yuno Payment Connector. Ese payload solo existe una vez que se ha ejecutado el paso de autorización de la transacción. La autorización es el paso 1 del flujo de la transacción de pago de VTEX. Cuando el comprador realiza la orden, VTEX llama al Payment Connector con los detalles de la orden (productos, montos, comprador, envío). El Connector procesa esa solicitud y devuelve una respuesta que incluye el payload. El SDK necesita este payload para configurarse y montarse para esa orden específica.
Activa siempre el paso de autorización antes de montar el SDK. Si lo montas sin el payload devuelto por el Connector, el SDK no tiene contexto de pago que renderizar y el checkout no se cargará.

Pasos de integración

1

Instala el SDK

El Yuno SDK Web for VTEX se publica en npm como @yuno-payments/sdk-web-vtex. Instálalo en tu proyecto con el gestor de paquetes que prefieras:
2

Monta el SDK

Monta el SDK en la página donde el comprador completa el pago. Inicialízalo llamando al método mount con un objeto de configuración:
Mantén el SDK montado mientras el comprador paga. Llama a unmount solo cuando desmontes el checkout, por ejemplo, cuando se destruya el componente o el comprador navegue a otra página:

Usar el Headless SDK dentro de una app móvil

El Yuno SDK Web for VTEX es una librería web. Para usarlo dentro de una app móvil, cargas la página de tu front-end (la que monta el SDK) dentro de un WebView. El WebView es lo que le da al SDK el entorno de navegador que necesita para ejecutarse.

Qué es un WebView y por qué lo necesitas

Un WebView es un componente de navegador integrable que renderiza contenido web dentro de una app nativa (WebView en Android, WKWebView en iOS y wrappers como react-native-webview). Como el SDK se ejecuta en el navegador, el WebView es lo que le da ese entorno de navegador. Tu app carga la URL que monta el SDK, y el SDK renderiza el checkout dentro del WebView. Los detalles de implementación que siguen son sugerencias. Cómo construyas el WebView y el puente depende por completo de ti. El objetivo es solo mostrar qué debe existir para que el SDK funcione.

El puente entre tu app y el WebView

Tu app y la página dentro del WebView necesitan comunicarse en ambas direcciones:
  • Web → App: la página informa los resultados a la app nativa (por ejemplo, pago completado, error o estado de carga). Todas las plataformas de WebView exponen un canal de mensajes para esto: window.ReactNativeWebView.postMessage(...), una interfaz de JavaScript en Android o un WKScriptMessageHandler en iOS.
  • App → Web: la app inyecta/evalúa JavaScript en la página (por ejemplo, para entregar el payload después de que la página se cargue).
Recomendamos definir un pequeño contrato de mensajes que la página emita y la app escuche. Por ejemplo:
Cuando el SDK llama a onPaymentDone, onError o onLoading, tu página reenvía un mensaje con esta forma a través del puente. Luego la app reacciona cerrando el WebView, mostrando el resultado o activando un indicador de carga. Los nombres exactos de los campos los defines tú.

Consideraciones técnicas

Para que el SDK funcione dentro de un WebView, asegúrate de que el WebView tenga:
  • JavaScript habilitado.
  • DOM storage habilitado (el SDK usa el almacenamiento del navegador).
  • Cookies de terceros / compartidas habilitadas, para que la sesión de pago se conserve entre las solicitudes que hace el SDK.
  • Un puente configurado (consulta lo anterior) para que los resultados puedan regresar a la app.

Wallets: Apple Pay y Google Pay

Las wallets tienen requisitos adicionales además de la configuración general, porque interviene la superficie de pago nativa del dispositivo.

Google Pay (WebView de Android)

Google Pay dentro de un WebView de Android depende de la Payment Request API de Chromium y de abrir la hoja de Google Pay. Para que funcione:
  • Habilita la Payment Request API en el WebView. En Android esto se hace mediante androidx.webkit (WebSettingsCompat.setPaymentRequestEnabled(...)) cuando la función es compatible.
  • Permite que se abra la hoja de la wallet. Google Pay abre su hoja mediante window.open(). Un WebView predeterminado puede bloquearla (es posible que veas un error OR_BIBED_15 / “pop-ups turned off”). Configura el WebView para que la nueva ventana se cargue en el mismo WebView en lugar de requerir un popup bloqueado.
  • Declara los intents de Google Pay que tu app puede consultar, en el manifiesto de Android, para que el WebView pueda acceder al servicio de Google Pay:
Algunas condiciones no dependen del código de tu app sino del dispositivo donde se realiza el pago. Aplican tanto al dispositivo de un comprador como a cualquier dispositivo que uses para probar el flujo. El dispositivo necesita un Android System WebView y Google Play services actualizados, y una cuenta de Google con un método de pago válido agregado. Para ver todos los detalles, consulta la guía de Google Using Google Pay with an Android WebView.

Apple Pay (WebView de iOS)

Apple Pay tiene un requisito estricto sobre desde dónde se sirve la página: no puede ejecutarse desde un archivo HTML local estático cargado en el WebView. La página que monta el SDK debe servirse desde una URL alojada cuyo dominio esté registrado y verificado en tu cuenta de Apple Developer. Ese dominio también debe estar configurado en tu Yuno dashboard para que todos los dominios involucrados coincidan. Si los dominios no coinciden, Apple Pay no estará disponible.

Ejemplos

Los fragmentos siguientes son solo ejemplos de referencia. Muestran una forma posible de conectar el WebView y el puente en cada stack. No son una elección tecnológica obligatoria ni recomendada; usa lo que mejor se adapte a tu app.
Carga la página alojada en un WebView, habilita los ajustes compatibles con wallets y escucha los mensajes de la página. La entrega del payload a la página (después del paso de autorización) y el contrato de mensajes dependen de ti.
Habilitar la Payment Request API de Android (setPaymentRequestEnabled) no está expuesto por react-native-webview de forma predeterminada; requiere un pequeño ajuste nativo en la configuración del WebView.
Habilita JavaScript, registra una interfaz de JavaScript para el canal Web → App e inyecta el payload una vez que la página se haya cargado.
Para Google Pay, habilita también la Payment Request API en settings mediante WebSettingsCompat.setPaymentRequestEnabled(...) y agrega al manifiesto los intents de <queries> mostrados anteriormente.
Registra un WKScriptMessageHandler para el canal Web → App e inyecta el payload cuando la página termine de cargarse. Recuerda que Apple Pay requiere una URL alojada y verificada (no un archivo local).

Recursos