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 TokensyCreate Customerestá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 unpayload 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.
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:Referencia de configuración
Referencia de configuración
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 unWKScriptMessageHandleren iOS. - App → Web: la app inyecta/evalúa JavaScript en la página (por ejemplo, para entregar el
payloaddespués de que la página se cargue).
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 errorOR_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:
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.React Native (react-native-webview)
React Native (react-native-webview)
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 porreact-native-webviewde forma predeterminada; requiere un pequeño ajuste nativo en la configuración del WebView.
Android (WebView nativo)
Android (WebView nativo)
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 ensettingsmedianteWebSettingsCompat.setPaymentRequestEnabled(...)y agrega al manifiesto los intents de<queries>mostrados anteriormente.
iOS (WKWebView)
iOS (WKWebView)
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