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.
- Marca blanca del SDK: el SDK Web de Yuno cargado desde un host externo, para verificar los globales, eventos y tokens del DOM renombrados.
- Marca blanca del checkout alojado (enlace de pago): la aplicación
sdk-checkout(normalmentecheckout.<env>.y.uno) detrás del origen o la subruta del comercio, de modo quecheckout.y.uno/payment?session=…se pueda mapear atheir.host/<base-path>/payment?session=….
Por qué existe este servidor
Históricamente, el SDK Web de Yuno incluye una superficie con el prefijoyuno-: window.Yuno, el evento yuno-sdk-ready y las clases CSS y atributos de datos yuno-*. La versión de marca blanca introduce una superficie paralela:
Para verificar que el cambio de nombres realmente se publicó, el SDK debe cargarse desde un host que no sea
*.y.uno. Si se carga desde un origen de Yuno, las filtraciones de marca pasarían inadvertidas. Este servidor es ese entorno de pruebas: sirve el SDK desde localhost:9090 (o cualquier nombre de host que no sea de Yuno al que lo apuntes) y reenvía de forma transparente cada solicitud a los upstreams reales de Yuno.
El mismo entorno de pruebas también hace de frontal del checkout de enlace de pago alojado: sirve las rutas SPA de sdk-checkout desde el origen del proxy, reescribe el origen de recursos de la aplicación hacia sí mismo y reenvía el BFF del checkout y el WebSocket de estado al upstream. Esto permite aplicar marca blanca al checkout alojado sobre el origen o la subruta de un comercio sin que ninguna solicitud a *.y.uno se filtre desde la página. Consulta Marca blanca del checkout alojado (enlace de pago).
Cómo funciona
- El navegador solo se comunica con el origen del proxy. Ninguna solicitud a
*.y.unose origina en la propia página; de lo contrario, el SDK no se está probando realmente contra un host externo. - Todos los dominios upstream son accesibles desde el proxy. Los recursos del SDK, la micro-aplicación del formulario de tarjeta, la micro-aplicación de 3DS, la API REST y el servicio WebSocket son nombres de host distintos que deben poder configurarse cada uno.
- CORS lo gestiona el proxy, no el upstream. El CORS del upstream respondería con orígenes de
api.y.uno; el proxy los elimina y escribe los suyos, reflejando al que realiza la llamada.
Arquitectura
Un único proceso de Node.js construido con tres bibliotecas:express: enrutamiento y middleware para HTTP.node-fetch: HTTP saliente hacia los upstreams, para cuerpos en streaming y control de encabezados.http-proxy: actualizaciones a WebSocket, porque el middleware de Express nunca ve las solicitudesUpgrade.
Ciclo de vida de la solicitud
-
La eliminación de la subruta base se ejecuta antes que todo lo demás, y solo cuando
BASE_PATHestá definido. Reescribereq.url/req.originalUrlpara quitar la subruta configurada, de modo que toda la coincidencia y el reenvío posteriores vean rutas relativas a la raíz. No hace nada (ni siquiera se registra) en un montaje en la raíz. ConsultaBASE_PATH: montaje en subruta. -
El middleware de CORS se ejecuta a continuación. Refleja el
Originde quien llama, gestiona la verificación previaOPTIONSy estableceAccess-Control-Allow-Credentials: true. El proxy es la autoridad de CORS. -
Las rutas locales coinciden antes que cualquier otra:
/,/static/*,/whitelabel-info. Estas nunca llegan a un upstream. -
El pass-through del backend coincide con
/v1/*y/v2/*(la superficie REST de Yuno que usa el SDK) y reenvía mediantenode-fetchaBACKEND_URL. Los encabezados hop-by-hop se eliminan; los encabezadosaccess-control-*del upstream se descartan para que no puedan sobrescribir el CORS propio del proxy. El encabezadoCookiedel navegador también se descarta en estos reenvíos. Las cookies de localhost de la página del socio (de sesión, de analítica, con valores en forma de URL, …) no corresponden a una llamada entre orígenes aapi.y.unoy pueden activar el WAF del upstream con un403; la API se autentica mediante la clave de API pública. -
El pass-through del BFF del checkout coincide con
/checkout-bff/*y reenvía aCHECKOUT_BFF_UPSTREAM, compartiendo el mismo reenviador que el backend (cuerpo reserializado, encabezados hop-by-hop,access-control-*yCookieeliminados). La aplicaciónsdk-checkoutllama a su BFF mediante elapiUrlcon marca blanca (host/<base-path>/checkout-bff/v1), por lo que, tras eliminar la subruta base, el proxy ve/checkout-bff/*(GET /checkout-bff/v1/checkout-info/{session},POST /checkout-bff/v1/checkout/payment). Consulta Marca blanca del checkout alojado (enlace de pago). -
Las rutas SPA del checkout coinciden con
/payment,/payment/statusy/enroll(GET), registradas antes del catch-all del SDK. Cada una obtieneCHECKOUT_UPSTREAM/index.htmly reescribe el origen absoluto de recursos de la aplicación (PUBLIC_URL, por ejemplocheckout.<env>.y.uno) aBASE_PATH, de modo que el bundle de CRA, el favicon y el manifiesto se carguen de vuelta a través del proxy en lugar de filtrarse al host de Yuno. react-router resuelve la ruta real en el cliente a partir dewindow.location. -
El catch-all de SDK y recursos coincide con todos los
GET/HEADrestantes. Un pequeño despachador (pickSdkUpstream) elige el upstream correcto según la ruta, evaluando de arriba abajo, con cada regla anclada al inicio de la ruta (después de la subruta base), de modo que las reglas de checkout, 3DS y tarjeta se evalúen primero:- Recursos de la aplicación de checkout: el bundle de CRA (
/static/(js|css|media)/*) y los archivos públicos de la raíz (/favicon.ico,/manifest.json,/robots.txt,/asset-manifest.json) →CHECKOUT_UPSTREAM. Se evalúa primero para que no caigan en el upstream de iconos del SDK. - Rutas de la micro-aplicación de 3DS (
/challenge.html,/redirect.html,/session-id.htmly/assets/(challenge|redirect|session-id|validate-url)*) →SDK_3DS_UPSTREAM. - Rutas de la micro-aplicación de tarjeta (
/v<semver>/pages/*,/v<semver>/assets/*) →SDK_CARD_UPSTREAM. - Rutas de bundles estáticos (
/sdk-static-bundles-ms/*) →SDK_STATIC_BUNDLES_UPSTREAM(prod.y.uno). Desde el SDK 1.10.9, el SDK carga su hoja de estilos de fuentes desdeprod.y.uno/sdk-static-bundles-ms/v1/static/css/…, y la hoja de estilos carga sus archivoswoff2con URLs relativas../fonts/bajo el mismo prefijo. Desde el SDK 1.11.16, el script de Forter y la baliza SRI de Riskified también se solicitan desde este prefijo en el host de marca blanca (las versiones anteriores los solicitan directamente aprod.y.uno, sin pasar por el proxy). Se evalúa antes que la regla estática, porque sus rutas también contienen/static/css/,/static/js/y/fonts/. - Rutas de recursos estáticos (
/icons/*,/css/*,/brands/*,/c2p/*,/wallets/*,/fonts/*) →SDK_STATIC_UPSTREAM(sdk.prod.y.uno). - Rutas de recursos de iconos (
/sdk-web/*,/flags/*e imágenes de marca sueltas en la raíz como/Visa.png,/boleto_logosimbolo.png) →SDK_ICONS_UPSTREAM(icons.prod.y.uno). - Todo lo demás →
SDK_UPSTREAM.
icons.prod.y.uno/sdk.prod.y.uno, sin pasar por el host de marca blanca. Las compilaciones recientes del SDK los intercambian de host hacia el origen del proxy (conservando la ruta), por lo que el proxy debe reenviarlos de vuelta a las CDN según el prefijo de la ruta.sdk.prod.y.unoeicons.prod.y.unoson iguales en todos los entornos;/sdk-static-bundles-ms/*usaprod.y.unopor defecto (solo la baliza SRI de Riskified usastaging.y.unofuera de producción). - Recursos de la aplicación de checkout: el bundle de CRA (
-
Las actualizaciones a WebSocket se gestionan en el
http.Serversubyacente, no en Express./checkout-websocket-notification-ms/ws/{payment,enrollment}→BACKEND_WS_URL(el flujo de estado del checkout alojado); todo lo demás sigue la misma división de SDK / tarjeta / 3DS que HTTP.
Normalización de versiones
El bundle principal del SDK tiene versión (/v1.7.4/main.js). Hay dos complicaciones:
- Las páginas de los socios pueden tener fija una versión que el upstream ya no publica.
- La versión “actual” cambia con el tiempo.
/v<x>/* a esa versión antes de enviarla al upstream. Las rutas de la aplicación de tarjeta y de 3DS no se reescriben; tienen sus propios ciclos de publicación.
Marca blanca del checkout alojado (enlace de pago)
Un comercio aplica marca blanca al checkout alojado de Yuno mapeandocheckout.<env>.y.uno/payment?session=… a su propio host/<BASE_PATH>/payment?session=…. El entorno de pruebas emula esto de forma local con dos upstreams: CHECKOUT_UPSTREAM (la estructura de la aplicación sdk-checkout) y CHECKOUT_BFF_UPSTREAM (el BFF al que llama):
- Rutas SPA:
/payment,/payment/statusy/enrollobtienen cada unaCHECKOUT_UPSTREAM/index.html. Los enlaces a recursos del HTML servido son absolutos (PUBLIC_URL=checkout.<env>.y.uno), por lo que el proxy reescribe ese origen aBASE_PATH, manteniendo el bundle de CRA, el favicon y el manifiesto en el origen del proxy en lugar de filtrarse de vuelta al host de Yuno. react-router resuelve la ruta real en el cliente a partir dewindow.location. - Llamadas al BFF: el
baseURLde axios de la aplicación de checkout es elapiUrlcon marca blanca (host/<BASE_PATH>/checkout-bff/v1). Tras eliminar la subruta base, el proxy ve/checkout-bff/*y lo reenvía aCHECKOUT_BFF_UPSTREAM(GET /checkout-bff/v1/checkout-info/{session},POST /checkout-bff/v1/checkout/payment). La cotización de promoción no va al BFF: el SDK dentro del checkout la solicita mediante el pass-through del backend (POST /v1/promotions/quote), por lo que un proxy que solo reenvía rutas explícitas debe reenviar también esa, o el cliente verá en silencio el precio regular. - WebSocket de estado:
/checkout-websocket-notification-ms/ws/{payment,enrollment}se reenvía aBACKEND_WS_URL.
El host del BFF es
<env>.y.uno directamente, sin el prefijo api- (sandbox.y.uno, prod.y.uno), a diferencia de la superficie REST del SDK en api[-env].y.uno. Configura CHECKOUT_UPSTREAM y CHECKOUT_BFF_UPSTREAM con el mismo entorno que tu sesión de checkout.http://localhost:9090<BASE_PATH>/payment?session=<checkout-session> con CHECKOUT_UPSTREAM / CHECKOUT_BFF_UPSTREAM que correspondan al entorno de la sesión. El checkout se muestra bajo el origen que no es de Yuno y llama al BFF de vuelta a través del proxy.
SDK_MAIN_JS: fijar la versión del SDK
SDK_MAIN_JS decide qué compilación del SDK carga cada navegador. Hace dos cosas relacionadas:
- Inyección de plantilla. El proxy sirve
pages/index.htmlcon el marcador literal__SDK_MAIN_JS__reemplazado por esta ruta. Una página de un socio puede escribir<script src="__SDK_MAIN_JS__">y obtener, por ejemplo,/v1.9.4/main.js. - Destino de la normalización de versiones. El proxy extrae el segmento
/v<x>/deSDK_MAIN_JSy reescribe cualquier solicitud entrante/v<other>/main.js(y los adyacentes/v<other>/*.js,/v<other>/*.css) a esa misma versión. Así, siSDK_MAIN_JS=/v1.9.4/main.js, una solicitud de/v1.5.0/main.jsse obtiene en silencio como/v1.9.4/main.jsdesdeSDK_UPSTREAM.
Orden de resolución al arrancar
SDK_MAIN_JS explícitamente es la única forma de omitir por completo la obtención desde el upstream. Esto es útil cuando versions.json no es accesible, quieres un arranque determinista o el latest del upstream no es contra lo que quieres probar.
Formato
<semver> coincide con [\d.]+(?:-[\w.]+)?: números separados por puntos con un sufijo de versión preliminar opcional.
La ruta debe comenzar con
/v y contener /main.js para que la normalización funcione. Si la expresión regular no coincide, la ruta se usa para la inyección de plantilla pero la reescritura de versiones queda desactivada.
Casos de uso comunes
Probar de extremo a extremo una versión específica del SDK:v1.9.4, y cualquier /v<other>/*.js fijo en las páginas de los socios se reescribe en silencio a v1.9.4 contra SDK_UPSTREAM.
Arranque silencioso (sin llamada a versions.json del upstream):
SDK_UPSTREAM es un servidor de archivos local que no expone versions.json.
Reproducir un error de un cliente en una versión anterior:
v1.7.4 siga publicada en SDK_UPSTREAM, cada navegador que llegue al proxy la carga, sin necesidad de recompilar.
Puntos a tener en cuenta
- Los upstreams de tarjeta y 3DS no se ven afectados.
SDK_MAIN_JSsolo fija la versión del bundle principal del SDK. La micro-aplicación de tarjeta (/v<x>/pages/*) y la micro-aplicación de 3DS mantienen sus propios segmentos de versión. - Definirlo desactiva la detección automática. Si se publica una versión más reciente del SDK en el upstream, sigues cargando la versión fijada hasta que cambies la variable de entorno y reinicies.
- Requiere reinicio. El valor se lee una sola vez al arrancar. No hay recarga en caliente.
- La discrepancia con el upstream es silenciosa. Fijar una versión que el upstream no publica produce un
404para/v<your-pin>/main.js. Revisa la pestaña de red para detectarlo. - Sin cadenas de consulta ni hash. Solo la ruta.
BASE_PATH: montaje en subruta
Un gateway de un socio suele estar montado bajo una subruta en lugar de en la raíz del origen. Zuora, por ejemplo, sirve el SDK desde https://host/hosted-payment-methods/hosted-payment-form/orchestrator en lugar de https://host/. Las compilaciones recientes del SDK conservan ese prefijo en cada solicitud de recursos, de API y de WebSocket (el apiUrl / assetUrl configurado lo incluye), por lo que una solicitud de un icono llega como …/orchestrator/sdk-web/foo.svg, no como /sdk-web/foo.svg.
Sin ayuda, esas rutas con prefijo nunca coincidirían con el enrutamiento a nivel de raíz del proxy. BASE_PATH cierra esa brecha: defínelo con la subruta bajo la que el proxy está “montado”, y el proxy elimina el prefijo de cada solicitud entrante (rutas locales, el reenvío de backend /v1–/v2, el catch-all de recursos y las actualizaciones a WebSocket) antes de enrutar. Las reglas existentes a nivel de raíz coinciden entonces sin cambios.
Déjalo vacío para un montaje en la raíz (el valor por defecto: el comportamiento es idéntico a no tener la función).
Qué cambia
- Eliminación del prefijo. Un middleware superior reescribe
req.url/req.originalUrlpara quitarBASE_PATH, de modo que todo lo posterior opere sobre rutas relativas a la raíz. Las actualizaciones a WebSocket reciben la misma eliminación en elhttp.Serversubyacente. - Inyección de plantilla. El marcador
__SDK_MAIN_JS__se emite con el prefijo, de modo que la página de inicio servida apunte a<BASE_PATH>/v<x>/main.js. /whitelabel-infoinforma elbasePathresuelto (onullen la raíz) junto con la configuración de upstreams.
Formato
Configuración de la página del socio
CuandoBASE_PATH está definido, la página del socio debe llevar el mismo prefijo en dos lugares:
- Carga el bundle desde
http://localhost:9090<BASE_PATH>/v<ver>/main.js. - Inicializa con
apiUrl/assetUrl=http://localhost:9090<BASE_PATH>.
assetUrl con versión. Puedes fijar una versión del bundle en assetUrl (…/orchestrator/v1.0). El SDK usa esa ruta para los chunks de JS pero elimina el /v<semver> final al resolver los recursos de CDN con host intercambiado (los iconos y las fuentes no tienen versión), por lo que tanto assetUrl = …/orchestrator como assetUrl = …/orchestrator/v1.0 enrutan correctamente los iconos.Puntos a tener en cuenta
- El prefijo vive en la URL, no en un encabezado. Tanto el
<script src>del bundle como elapiUrl/assetUrldeben incluirBASE_PATH, o las solicitudes llegan a la raíz y la eliminación nunca se ejercita. - La eliminación es de prefijo exacto. Solo se reescriben
BASE_PATH,BASE_PATH/…yBASE_PATH?…. Una ruta que solo se parece al prefijo se deja intacta. - Las actualizaciones a WebSocket también se eliminan, en el controlador
upgradedehttp.Server, ya que el middleware de Express nunca las ve.
Cómo construir un servidor como este
- Inicializa el proyecto
Usa
node-fetch@2 (CommonJS) a menos que tengas un paso de compilación; la v3 es solo ESM.
- Define tu mapa de upstreams
SDK_CARD_UPSTREAM y SDK_3DS_UPSTREAM usan SDK_UPSTREAM por defecto cuando no están definidos, y BACKEND_WS_URL usa BACKEND_URL por defecto. Conserva este comportamiento de respaldo, facilita las pruebas en un solo entorno. SDK_STATIC_UPSTREAM / SDK_ICONS_UPSTREAM / SDK_STATIC_BUNDLES_UPSTREAM son la excepción: usan por defecto los hosts fijos sdk.prod.y.uno / icons.prod.y.uno / prod.y.uno, no SDK_UPSTREAM. Los dos primeros son iguales en todos los entornos; define SDK_STATIC_BUNDLES_UPSTREAM como staging.y.uno para probar la baliza SRI de Riskified fuera de producción. CHECKOUT_UPSTREAM / CHECKOUT_BFF_UPSTREAM usan sandbox por defecto (checkout.sandbox.y.uno / sandbox.y.uno); la regla de recursos del checkout se evalúa antes que las reglas de iconos del SDK para que el bundle de CRA y los archivos de la raíz (/favicon.ico, …) no caigan en icons.prod.y.uno.
Si necesitas emular un gateway de un socio montado bajo una subruta, registra un middleware de eliminación antes de todas las rutas que reescriba
req.url / req.originalUrl para quitar BASE_PATH (y aplica la misma eliminación en el controlador upgrade de http.Server). Así, cada ruta siguiente ve rutas relativas a la raíz. Omítelo por completo cuando BASE_PATH esté vacío. Consulta BASE_PATH: montaje en subruta.
- Configura CORS como responsabilidad del proxy
*) para que las solicitudes con credenciales funcionen, y resuelve las verificaciones previas de inmediato. Cuando más adelante reenvíes las respuestas del upstream, elimina todos los encabezados access-control-* del upstream o sobrescribirán los tuyos.
- Filtra los encabezados hop-by-hop en ambas direcciones
Según RFC 7230 §6.1:
content-length es el error clásico: node-fetch lo establece, pero si además copias el valor original, la respuesta se trunca.
- Reenvía la superficie de la API
express.json() ya consumió el cuerpo de la solicitud, así que para los métodos que no son GET debes reserializar req.body. No intentes hacer req.pipe(upstream) después de que el cuerpo se haya consumido.
Elimina el encabezado
Cookie antes de reenviar. Las cookies del navegador de la página del socio pertenecen al origen del proxy (de sesión, de analítica, con valores en forma de URL como spage) y una llamada genuina entre orígenes a api.y.uno nunca las llevaría. Reenviarlas solo arriesga que el WAF del upstream rechace la solicitud con un 403. La API se autentica mediante la clave de API pública, no mediante cookies. (Las actualizaciones a WebSocket son la excepción; consulta el paso 7.)
- Catch-all del proxy para los recursos del SDK
- Gestiona las actualizaciones a WebSocket en el http.Server
El middleware de Express no ve las solicitudes Upgrade. Engánchate directamente al servidor http:
http-proxy negocia ws:// o wss:// a partir del esquema de la URL de destino.
- Conecta las variables de entorno
Usa dotenv. Documenta los valores por entorno, no solo los valores por defecto. Para Yuno:
- Los servicios del SDK siguen
<service>[.<env>].y.uno:sdk-web.y.uno,sdk-web.staging.y.uno,sdk-web.dev.y.uno. - La superficie de la API usa
api[-<env>].y.uno:api.y.uno,api-staging.y.uno,api-dev.y.uno. Ten en cuenta el guion, no un punto. - El servicio WebSocket no tiene el prefijo
api-; es<env>.y.unodirectamente (y.uno,staging.y.uno,dev.y.uno).
.env.example para que los usuarios no tengan que adivinar.
- Incluye una página de inicio mínima
Sirve index.html en / y un endpoint JSON /whitelabel-info que devuelva la configuración de upstreams resuelta. La página de inicio llama al endpoint JSON y lo muestra, de modo que quien depure el proxy vea exactamente qué se enruta a dónde sin revisar los registros.
Problemas frecuentes y casos límite
- El orden de las rutas importa. El catch-all del SDK se registra al final. Todo lo que agregues con
app.usedespués de él nunca se ejecuta. - La autoridad de CORS debe ser el proxy. Dejar pasar los encabezados
access-control-*del upstream hace que las solicitudes con credenciales entre orígenes fallen de forma aleatoria cuando la lista de permitidos del upstream no incluyelocalhost. - Los encabezados hop-by-hop son bidireccionales. Elimínalos en ambos sentidos.
content-lengthes el que causa problemas. - El consumo del cuerpo ocurre una sola vez. Cuando
express.json()analiza una solicitud, el flujo subyacente se vacía. Reserializa desdereq.bodysi necesitas reenviar unPOST. - Streaming, no almacenamiento en búfer, para los recursos.
upstream.body.pipe(res)mantiene la memoria estable incluso con bundles de varios MB. - La normalización de versiones es solo para
SDK_UPSTREAM. Las micro-aplicaciones de tarjeta y 3DS tienen sus propios segmentos de versión; reescribirlos rompe la URL del upstream. Las CDN de estáticos e iconos no tienen versión, por lo que tampoco se normalizan. - Los recursos estáticos de CDN también tienen el host intercambiado. Las compilaciones recientes del SDK reescriben sus URLs de recursos fijas
icons.prod.y.uno/sdk.prod.y.unohacia el host de marca blanca, por lo que el proxy debe reenviar/icons,/css,/brands,/c2p,/wallets,/fonts→sdk.prod.y.unoy/sdk-web,/flags,/*.pngsueltos →icons.prod.y.uno. Las compilaciones anteriores del SDK los cargan directamente desde la CDN y nunca llegan al proxy. Probar esto de extremo a extremo requiere una compilación reciente del SDK y una página de socio que se inicialice con{ apiUrl: '<proxy origin>' }(oassetUrl). - Las fuentes necesitan su propia ruta desde el SDK 1.10.9. El SDK carga su hoja de estilos de fuentes desde
prod.y.uno/sdk-static-bundles-ms/…, con el host intercambiado hacia el host de marca blanca. Sin una regla/sdk-static-bundles-ms/*→prod.y.uno, la solicitud cae enSDK_UPSTREAMy devuelve404. El SDK entonces se muestra con la fuente del sistema, sin ningún error. - No reenvíes las cookies de la página del socio a la API. Elimina
Cookieen los reenvíos de/v1//v2. Las cookies de localhost del navegador (de sesión, de analítica, con valores en forma de URL comospage) no corresponden a una llamada entre orígenes aapi.y.unoy pueden activar el WAF del upstream con un403. La API se autentica mediante la clave de API pública. - La autenticación de WebSocket son los encabezados que
http-proxyve. No eliminescookieniauthorizationde las actualizaciones a WebSocket; la eliminación de cookies se aplica solo a los reenvíos HTTP del backend/v1//v2. .envestá en gitignore. Mantén siempre.env.examplesincronizado; es la especificación para quien clone el repositorio.
Rutas que un proxy de socio debe reenviar
Un gateway de socio en producción necesita la misma división que este entorno de pruebas (esta tabla es la referencia; las listas anteriores describen el entorno de pruebas). Cada ruta llega bajo la subruta base del socio, con el prefijo exacto con el que la llevanapiUrl / assetUrl. Revisa esta lista antes de actualizar la línea del SDK.
Evalúa las reglas en este orden; gana la primera coincidencia. Varias formas se superponen (/v1/*, /v<major.minor>/*, /v<card-semver>/pages/*), por lo que un conjunto desordenado de reglas de prefijo o de expresiones regulares envía las páginas de tarjeta o las llamadas a la API al host equivocado.
La columna Necesario desde indica la versión del SDK a partir de la cual el SDK envía esa solicitud al host de marca blanca. Los recursos en sí son anteriores (el script de Forter vive bajo
/sdk-static-bundles-ms/ desde el SDK 1.5.19, la baliza SRI de Riskified desde la 1.6.4, el botón de Samsung Pay en portugués bajo /wallets/ desde la 1.10.9), pero antes de la versión indicada el SDK los solicitaba directamente a *.y.uno, por lo que un proxy de socio nunca los veía y no necesitaba ninguna regla. Agregar las reglas antes de actualizar es inofensivo.
| 9 | /sdk-web/*, /flags/*, imágenes de marca sueltas (/Visa.png, …) | icons.prod.y.uno | SDK 1.9.32+ |
| 10 | /v<major.minor>/* (bundle del SDK y chunks) y todo lo demás | sdk-web[.<env>].y.uno | Siempre |- CORS. Las fuentes (
/sdk-static-bundles-ms/*,/fonts/*) y los scripts SRI antifraude se obtienen en modo CORS desde la página del comercio, por lo que el gateway debe devolverAccess-Control-Allow-Originpara el origen del comercio.sdk.prod.y.uno/fonts/*no envía ninguno, así que reenviar la respuesta sin modificar no es suficiente. - Rechaza los segmentos
.y..de la ruta antes de reenviar. De lo contrario,/sdk-static-bundles-ms/../…se resuelve a cualquier ruta del host upstream, incluido el gateway de la API de producción. - Regiones. Con una sobrescritura de
apiUrl, el SDK ya no agrega la región de la clave de API pública a los hosts, por lo que un gateway que atienda claves de MENA debe enrutarlas por sí mismo a los hosts regionales. assetUrlcon versión (por ejemplo…/orchestrator/v1.0). Los chunks se solicitan bajo ese segmento de versión, por lo que el gateway debe mapearlo a una ruta publicada desdk-web(el entorno de pruebas lo normaliza a la última versión publicada).- Enlace de pago. Reescribe el origen absoluto
checkout.<env>.y.unoen elindex.htmlservido a tu subruta base, como hace el entorno de pruebas, o el bundle se carga desde el host de Yuno. - Respaldo. El SDK 1.11.16+ vuelve a cargar desde Yuno los scripts antifraude, el botón de Samsung Pay en portugués y las fuentes de Checkout Builder cuando el gateway no puede servirlos, por lo que una regla faltante degrada el servicio en lugar de romperlo. Mantener todas las solicitudes fuera de
*.y.unosigue requiriendo todas las reglas anteriores.
Lista de verificación
Cuando tu proxy esté en ejecución, verifica en las DevTools del navegador:- Pestaña de red: ninguna solicitud a un host
*.y.unose origina en la página del comercio. Todo el tráfico va al origen del proxy. window.SdkPaymentsestá definido;window.Yunono está definido o es un alias heredado.- El evento
sdk-payments-readyse dispara endocumentdespués de que el SDK arranca. - No hay tokens del DOM
yuno-*en la salida renderizada, excepto los de la lista de permitidos de la marca de confianza (yuno-badge,secure-by-yuno,yuno-typography-provider,yuno-c2p,yuno-redirect,yuno-debug,data-yuno-session-id).
Implementación de referencia
El código fuente completo está en el repositorioyuno-sdk-web/white-label-proxy-server. Son unas 350 líneas en server.js; todo cabe en un solo archivo porque no hay lógica de negocio, solo enrutamiento y manejo de encabezados.
Ver también
- Marca blanca (SDK Web): las sobrescrituras del lado del SDK que este entorno de pruebas verifica.
- yuno-payments/yuno-sdk-web/tree/main/white-label-proxy-server: código fuente completo.
- RFC 7230 §6.1: encabezados específicos de la conexión
- Documentación de WebSocket de http-proxy