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.
Un pequeño servidor Express que emula el origen propio de un comercio (o una subruta) frente al stack de Yuno. Permite probar de extremo a extremo ambas superficies de marca blanca desde un origen que no es de Yuno antes de lanzar una integración alojada por un socio:
  • 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 (normalmente checkout.<env>.y.uno) detrás del origen o la subruta del comercio, de modo que checkout.y.uno/payment?session=… se pueda mapear a their.host/<base-path>/payment?session=….
Esta página complementa la página Marca blanca. Léela primero para conocer las sobrescrituras del lado del SDK que este entorno de pruebas está diseñado para verificar.

Por qué existe este servidor

Históricamente, el SDK Web de Yuno incluye una superficie con el prefijo yuno-: 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

Tres invariantes hacen útil este entorno de pruebas:
  1. El navegador solo se comunica con el origen del proxy. Ninguna solicitud a *.y.uno se origina en la propia página; de lo contrario, el SDK no se está probando realmente contra un host externo.
  2. 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.
  3. 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 solicitudes Upgrade.

Ciclo de vida de la solicitud

  1. La eliminación de la subruta base se ejecuta antes que todo lo demás, y solo cuando BASE_PATH está definido. Reescribe req.url / req.originalUrl para 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. Consulta BASE_PATH: montaje en subruta.
  2. El middleware de CORS se ejecuta a continuación. Refleja el Origin de quien llama, gestiona la verificación previa OPTIONS y establece Access-Control-Allow-Credentials: true. El proxy es la autoridad de CORS.
  3. Las rutas locales coinciden antes que cualquier otra: /, /static/*, /whitelabel-info. Estas nunca llegan a un upstream.
  4. El pass-through del backend coincide con /v1/* y /v2/* (la superficie REST de Yuno que usa el SDK) y reenvía mediante node-fetch a BACKEND_URL. Los encabezados hop-by-hop se eliminan; los encabezados access-control-* del upstream se descartan para que no puedan sobrescribir el CORS propio del proxy. El encabezado Cookie del 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 a api.y.uno y pueden activar el WAF del upstream con un 403; la API se autentica mediante la clave de API pública.
  5. El pass-through del BFF del checkout coincide con /checkout-bff/* y reenvía a CHECKOUT_BFF_UPSTREAM, compartiendo el mismo reenviador que el backend (cuerpo reserializado, encabezados hop-by-hop, access-control-* y Cookie eliminados). La aplicación sdk-checkout llama a su BFF mediante el apiUrl con 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).
  6. Las rutas SPA del checkout coinciden con /payment, /payment/status y /enroll (GET), registradas antes del catch-all del SDK. Cada una obtiene CHECKOUT_UPSTREAM/index.html y reescribe el origen absoluto de recursos de la aplicación (PUBLIC_URL, por ejemplo checkout.<env>.y.uno) a BASE_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 de window.location.
  7. El catch-all de SDK y recursos coincide con todos los GET/HEAD restantes. 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.html y /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 desde prod.y.uno/sdk-static-bundles-ms/v1/static/css/…, y la hoja de estilos carga sus archivos woff2 con 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 a prod.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.
    Las ramas de estáticos e iconos existen porque el SDK solía cargar estos recursos directamente desde 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.uno e icons.prod.y.uno son iguales en todos los entornos; /sdk-static-bundles-ms/* usa prod.y.uno por defecto (solo la baliza SRI de Riskified usa staging.y.uno fuera de producción).
  8. Las actualizaciones a WebSocket se gestionan en el http.Server subyacente, 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.
El proxy resuelve la versión canónica una sola vez al arrancar y reescribe cada solicitud entrante del SDK /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. Un comercio aplica marca blanca al checkout alojado de Yuno mapeando checkout.<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/status y /enroll obtienen cada una CHECKOUT_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 a BASE_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 de window.location.
  • Llamadas al BFF: el baseURL de axios de la aplicación de checkout es el apiUrl con marca blanca (host/<BASE_PATH>/checkout-bff/v1). Tras eliminar la subruta base, el proxy ve /checkout-bff/* y lo reenvía a CHECKOUT_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 a BACKEND_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.
La aplicación sdk-checkout valida el apiUrl / assetUrl con marca blanca contra una lista de permitidos (REACT_APP_WHITE_LABEL_ALLOWED_HOSTS). Para probar esto a través del proxy, localhost debe estar en esa lista de permitidos en el entorno de destino; de lo contrario, la aplicación ignora la sobrescritura y llama directamente a Yuno.
Para probarlo, abre 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:
  1. Inyección de plantilla. El proxy sirve pages/index.html con 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.
  2. Destino de la normalización de versiones. El proxy extrae el segmento /v<x>/ de SDK_MAIN_JS y reescribe cualquier solicitud entrante /v<other>/main.js (y los adyacentes /v<other>/*.js, /v<other>/*.css) a esa misma versión. Así, si SDK_MAIN_JS=/v1.9.4/main.js, una solicitud de /v1.5.0/main.js se obtiene en silencio como /v1.9.4/main.js desde SDK_UPSTREAM.

Orden de resolución al arrancar

Si los pasos 1 y 2 fallan, obtienes el valor de respaldo y se registra una advertencia. Definir 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:
Ahora cada página carga 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):
Útil en entornos aislados de la red o cuando SDK_UPSTREAM es un servidor de archivos local que no expone versions.json. Reproducir un error de un cliente en una versión anterior:
Mientras 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_JS solo 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 404 para /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

  1. Eliminación del prefijo. Un middleware superior reescribe req.url / req.originalUrl para quitar BASE_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 el http.Server subyacente.
  2. 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.
  3. /whitelabel-info informa el basePath resuelto (o null en la raíz) junto con la configuración de upstreams.

Formato

Barra inicial, sin barra final (las barras finales se eliminan). Vacío o sin definir = montaje en la raíz.

Configuración de la página del socio

Cuando BASE_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 el apiUrl / assetUrl deben incluir BASE_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/… y BASE_PATH?…. Una ruta que solo se parece al prefijo se deja intacta.
  • Las actualizaciones a WebSocket también se eliminan, en el controlador upgrade de http.Server, ya que el middleware de Express nunca las ve.

Cómo construir un servidor como este

  1. Inicializa el proyecto

Usa node-fetch@2 (CommonJS) a menos que tengas un paso de compilación; la v3 es solo ESM.

  1. 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.

  1. Configura CORS como responsabilidad del proxy

Refleja el origen de quien llama (no *) 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.

  1. Filtra los encabezados hop-by-hop en ambas direcciones

Según RFC 7230 §6.1:
Filtra estos encabezados tanto de los entrantes (solicitud al upstream) como de los salientes (upstream al cliente). Olvidar content-length es el error clásico: node-fetch lo establece, pero si además copias el valor original, la respuesta se trunca.

  1. 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.)

  1. Catch-all del proxy para los recursos del SDK

Registra el catch-all al final. Coincide con todo, por lo que cualquier middleware agregado después es inalcanzable a menos que lo protejas explícitamente.

  1. 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.

  1. 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.uno directamente (y.uno, staging.y.uno, dev.y.uno).
Estas inconsistencias de nomenclatura causan más errores 404 que cualquier otra clase de error. Inclúyelas en tu .env.example para que los usuarios no tengan que adivinar.

  1. 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.use despué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 incluye localhost.
  • Los encabezados hop-by-hop son bidireccionales. Elimínalos en ambos sentidos. content-length es 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 desde req.body si necesitas reenviar un POST.
  • 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.uno hacia el host de marca blanca, por lo que el proxy debe reenviar /icons, /css, /brands, /c2p, /wallets, /fonts → sdk.prod.y.uno y /sdk-web, /flags, /*.png sueltos → 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>' } (o assetUrl).
  • 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 en SDK_UPSTREAM y devuelve 404. 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 Cookie en los reenvíos de /v1//v2. Las cookies de localhost del navegador (de sesión, de analítica, con valores en forma de URL como spage) no corresponden a una llamada entre orígenes a api.y.uno y pueden activar el WAF del upstream con un 403. La API se autentica mediante la clave de API pública.
  • La autenticación de WebSocket son los encabezados que http-proxy ve. No elimines cookie ni authorization de las actualizaciones a WebSocket; la eliminación de cookies se aplica solo a los reenvíos HTTP del backend /v1//v2.
  • .env está en gitignore. Mantén siempre .env.example sincronizado; 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 llevan apiUrl / 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 devolver Access-Control-Allow-Origin para 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.
  • assetUrl con 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 de sdk-web (el entorno de pruebas lo normaliza a la última versión publicada).
  • Enlace de pago. Reescribe el origen absoluto checkout.<env>.y.uno en el index.html servido 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.uno sigue requiriendo todas las reglas anteriores.

Lista de verificación

Cuando tu proxy esté en ejecución, verifica en las DevTools del navegador:
  1. Pestaña de red: ninguna solicitud a un host *.y.uno se origina en la página del comercio. Todo el tráfico va al origen del proxy.
  2. window.SdkPayments está definido; window.Yuno no está definido o es un alias heredado.
  3. El evento sdk-payments-ready se dispara en document después de que el SDK arranca.
  4. 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 repositorio yuno-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