White Label Proxy Server

• SDK white-label: the Yuno Web SDK loaded from a foreign host, verifying the renamed globals, events, and DOM tokens.
• Hosted checkout white-label (Payment Link): the sdk-checkout app (normally checkout.<env>.y.uno) fronted by the merchant origin/sub-path, so checkout.y.uno/payment?session=… can be mapped onto their.host/<base-path>/payment?session=….

​

Why this server exists

​

How it works

┌──────────────────┐     ┌────────────────────────────┐     ┌─────────────────────┐
│  Partner page    │───▶ │   white-label-proxy        │───▶ │ Yuno upstreams      │
│  (browser)       │     │   (Express :9090)          │     │  - checkout.*.y.uno │
│                  │ ◀───│                            │ ◀───│  - sdk-web.*.y.uno  │
│ <script src=     │     │   Routes by path:          │     │  - sdk-3ds.*.y.uno  │
│  localhost:9090/ │     │  /payment,/enroll → CHECKOUT│     │  - sdk-web-card.*   │
│  v1.7/main.js>   │     │  /checkout-bff/*  → BFF     │     │  - sdk.prod.y.uno   │
│   ─ or ─         │     │    /v1/*         → BACKEND  │     │  - icons.prod.y.uno │
│  /payment?       │     │    /v<n>/pages    → CARD    │     │  - <env>.y.uno (BFF)│
│  session=…       │     │    /challenge     → 3DS     │     │  - api[-env].y.uno  │
│                  │     │    /icons,/css    → STATIC  │     │                     │
│                  │     │    /flags,/*.png  → ICONS   │     │                     │
│                  │     │    else           → SDK     │     │                     │
└──────────────────┘     └────────────────────────────┘     └─────────────────────┘

1. The browser only ever talks to the proxy origin. No *.y.uno request originates from the page itself; otherwise the SDK is not really being tested against a foreign host.
2. All upstream domains are reachable from the proxy. SDK assets, the card-form micro-app, the 3DS micro-app, the REST API, and the WebSocket service are all separate hostnames that must each be configurable.
3. CORS is owned by the proxy, not the upstream. Upstream CORS would respond with api.y.uno origins; the proxy strips those and writes its own, echoing the caller.

​

Architecture

• express: routing and middleware for HTTP.
• node-fetch: outbound HTTP to upstreams, for streaming bodies and header control.
• http-proxy: WebSocket upgrades, because Express middleware never sees Upgrade requests.

​

Request lifecycle

0. Base-path strip runs before everything else, and only when BASE_PATH is set. It rewrites req.url / req.originalUrl to drop the configured sub-path so all downstream matching and forwarding sees root-relative paths. A no-op (not even registered) for a root mount. See BASE_PATH: sub-path mounting.
1. CORS middleware runs next. It echoes the caller’s Origin, handles OPTIONS preflight, and sets Access-Control-Allow-Credentials: true. The proxy is the CORS authority.
2. Local routes match before anything else: /, /static/*, /whitelabel-info. These never touch an upstream.
3. Backend pass-through matches /v1/* and /v2/* (the Yuno REST surface used by the SDK) and forwards via node-fetch to BACKEND_URL. Hop-by-hop headers are stripped; access-control-* headers from the upstream are dropped so they cannot override the proxy’s own CORS. The browser Cookie header is also dropped on these forwards. The partner page’s localhost cookies (session, analytics, URL-valued ones, …) don’t belong on a cross-origin call to api.y.uno and can trip the upstream WAF with a 403; the API authenticates via the public API key.
4. Checkout BFF pass-through matches /checkout-bff/* and forwards to CHECKOUT_BFF_UPSTREAM, sharing the same forwarder as the backend (body re-serialized, hop-by-hop and access-control-* and Cookie stripped). The sdk-checkout app calls its BFF through the white-labeled apiUrl (host/<base-path>/checkout-bff/v1), so after the base-path strip the proxy sees /checkout-bff/* (GET /checkout-bff/v1/checkout-info/{session}, POST /checkout-bff/v1/checkout/payment). See Hosted checkout white-label (Payment Link).
5. Checkout SPA routes match /payment, /payment/status, and /enroll (GET), registered before the SDK catch-all. Each fetches CHECKOUT_UPSTREAM/index.html and rewrites the app’s absolute asset origin (PUBLIC_URL, e.g. checkout.<env>.y.uno) to BASE_PATH, so the CRA bundle, favicon, and manifest load back through the proxy instead of leaking to the Yuno host. react-router resolves the actual route client-side from window.location.
6. SDK/asset catch-all matches every remaining GET/HEAD. A small dispatcher (pickSdkUpstream) picks the right upstream based on path, checked top to bottom so the checkout/3DS/card rules win first:
   • Checkout app assets: the CRA bundle (/static/(js|css|media)/*) and root public files (/favicon.ico, /manifest.json, /robots.txt, /asset-manifest.json) → CHECKOUT_UPSTREAM. Checked first so they don’t fall through to the SDK icon upstream.
   • 3DS micro-app paths (/challenge.html, /redirect.html, /session-id.html, and /assets/(challenge|redirect|session-id|validate-url)*) → SDK_3DS_UPSTREAM.
   • Card micro-app paths (/v<semver>/pages/*, /v<semver>/assets/*) → SDK_CARD_UPSTREAM.
   • Static-asset paths (/icons/*, /css/*, /brands/*, /c2p/*) → SDK_STATIC_UPSTREAM (sdk.prod.y.uno).
   • Icon-asset paths (/sdk-web/*, /flags/*, and bare root brand images like /Visa.png, /boleto_logosimbolo.png) → SDK_ICONS_UPSTREAM (icons.prod.y.uno).
   • Everything else → SDK_UPSTREAM.
   The static / icons branches exist because the SDK used to load these straight from icons.prod.y.uno / sdk.prod.y.uno, bypassing the white-label host. Recent SDK builds host-swap them onto the proxy origin (path preserved), so the proxy must forward them back out to the two CDNs by path prefix. These upstreams are always *.prod.y.uno regardless of the target environment.
7. WebSocket upgrades are handled on the underlying http.Server, not Express. /checkout-websocket-notification-ms/ws/{payment,enrollment} → BACKEND_WS_URL (the hosted-checkout status stream); everything else follows the same SDK / card / 3DS split as HTTP.

​

Version normalization

• Partner pages may hardcode a version that the upstream no longer publishes.
• The “current” version drifts over time.

​

Hosted checkout white-label (Payment Link)

• SPA routes: /payment, /payment/status, and /enroll each fetch CHECKOUT_UPSTREAM/index.html. The served HTML’s asset links are absolute (PUBLIC_URL = checkout.<env>.y.uno), so the proxy rewrites that origin to BASE_PATH, keeping the CRA bundle, favicon, and manifest on the proxy origin instead of leaking back to the Yuno host. react-router resolves the actual route client-side from window.location.
• BFF calls: the checkout app’s axios baseURL is the white-labeled apiUrl (host/<BASE_PATH>/checkout-bff/v1). After the base-path strip the proxy sees /checkout-bff/* and forwards it to CHECKOUT_BFF_UPSTREAM (GET /checkout-bff/v1/checkout-info/{session}, POST /checkout-bff/v1/checkout/payment).
• Status WebSocket: /checkout-websocket-notification-ms/ws/{payment,enrollment} is forwarded to BACKEND_WS_URL.

​

SDK_MAIN_JS — pinning the SDK version

1. Template injection. The proxy serves pages/index.html with the literal __SDK_MAIN_JS__ placeholder replaced by this path. A partner page can write <script src="__SDK_MAIN_JS__"> and get, for example, /v1.9.4/main.js.
2. Version normalization target. The proxy parses the /v<x>/ segment out of SDK_MAIN_JS and rewrites any incoming /v<other>/main.js (and adjacent /v<other>/*.js, /v<other>/*.css) request to that same version. So if SDK_MAIN_JS=/v1.9.4/main.js, a request for /v1.5.0/main.js is silently fetched as /v1.9.4/main.js from SDK_UPSTREAM.

​

Resolution order at boot

1. process.env.SDK_MAIN_JS                          (if set, used as-is, no upstream call)
2. <SDK_UPSTREAM>/versions.json → latest.version    (auto-detect, 5s timeout)
3. /v1.7/main.js                                    (hard-coded fallback)

​

Format

SDK_MAIN_JS=/v<semver>/main.js

​

Common use cases

SDK_MAIN_JS=/v1.9.4/main.js npm start

SDK_MAIN_JS=/v1.9.4/main.js npm start

SDK_MAIN_JS=/v1.7.4/main.js npm start

​

Gotchas

• Card and 3DS upstreams are not affected. SDK_MAIN_JS only pins the main SDK bundle’s version. The card micro-app (/v<x>/pages/*) and the 3DS micro-app keep their own version segments.
• Setting it disables auto-detection. If a newer SDK version is published upstream, you keep loading the pinned version until you change the env var and restart.
• Restart required. The value is read once at boot. No hot reload.
• Mismatch with upstream is silent. Pinning to a version the upstream does not publish results in a 404 for /v<your-pin>/main.js. Check the network tab to spot it.
• No query strings or hash. Path only.

​

BASE_PATH — sub-path mounting

​

What it changes

1. Prefix strip. A top middleware rewrites req.url / req.originalUrl to drop BASE_PATH so everything downstream operates on root-relative paths. WebSocket upgrades get the same strip on the underlying http.Server.
2. Template injection. The __SDK_MAIN_JS__ placeholder is emitted with the prefix, so the served landing page points at <BASE_PATH>/v<x>/main.js.
3. /whitelabel-info reports the resolved basePath (or null at root) alongside the upstream config.

​

Format

BASE_PATH=/hosted-payment-methods/hosted-payment-form/orchestrator

​

Partner page setup

• Load the bundle from http://localhost:9090<BASE_PATH>/v<ver>/main.js.
• Initialize with apiUrl / assetUrl = http://localhost:9090<BASE_PATH>.

icon → http://localhost:9090/hosted-payment-methods/.../orchestrator/sdk-web/foo.svg
     → strip BASE_PATH → /sdk-web/foo.svg → SDK_ICONS_UPSTREAM

​

Gotchas

• The prefix lives in the URL, not a header. Both the bundle <script src> and the apiUrl / assetUrl must include BASE_PATH, or requests land at the root and the strip is never exercised.
• Strip is exact-prefix. Only BASE_PATH, BASE_PATH/…, and BASE_PATH?… are rewritten. A path that merely resembles the prefix is left alone.
• WebSocket upgrades are stripped too, on the http.Server upgrade handler, since Express middleware never sees them.

​

Building a server like this

​

1. Bootstrap the project

mkdir my-proxy && cd my-proxy
npm init -y
npm install express http-proxy node-fetch@2 dotenv

​

2. Define your upstream map

​

3. Set up CORS as the proxy’s responsibility

app.use((req, res, next) => {
  const origin = req.headers.origin
  if (origin) {
    res.set('access-control-allow-origin', origin)
    res.set('access-control-allow-credentials', 'true')
    res.set('vary', 'origin')
  } else {
    res.set('access-control-allow-origin', '*')
  }
  res.set('access-control-allow-methods', req.headers['access-control-request-method'] || 'GET,HEAD,PUT,PATCH,POST,DELETE,OPTIONS')
  res.set('access-control-allow-headers', req.headers['access-control-request-headers'] || '*')
  res.set('access-control-expose-headers', '*')
  res.set('access-control-max-age', '86400')
  if (req.method === 'OPTIONS') return res.status(204).end()
  next()
})

​

4. Filter hop-by-hop headers in both directions

const HOP_BY_HOP = new Set([
  'host', 'connection', 'keep-alive',
  'proxy-authenticate', 'proxy-authorization',
  'te', 'trailer', 'transfer-encoding', 'upgrade',
  'content-length', // node-fetch sets this itself
])

​

5. Forward the API surface

app.all('/v1/*', forwardToBackend)
app.all('/v2/*', forwardToBackend)

async function forwardToBackend(req, res) {
  const targetUrl = `${BACKEND_URL}${req.originalUrl}`
  const headers = pickRequestHeaders(req) // filters HOP_BY_HOP
  delete headers.cookie                   // partner cookies don't belong on api.y.uno
  const init = { method: req.method, headers }
  if (req.method !== 'GET' && req.method !== 'HEAD') {
    // express.json() consumed the original body; re-serialize it.
    init.body = req.body && Object.keys(req.body).length ? JSON.stringify(req.body) : undefined
    if (init.body && !headers['content-type']) headers['content-type'] = 'application/json'
  }
  const upstream = await fetch(targetUrl, init)
  res.status(upstream.status)
  for (const [k, v] of upstream.headers.entries()) {
    const lk = k.toLowerCase()
    if (HOP_BY_HOP.has(lk)) continue
    if (lk.startsWith('access-control-')) continue   // proxy owns CORS
    res.set(k, v)
  }
  res.send(await upstream.text())
}

​

6. Catch-all proxy for SDK assets

app.use((req, res, next) => {
  if (req.method !== 'GET' && req.method !== 'HEAD') return next()
  proxyToUpstream(req, res, next)
})

async function proxyToUpstream(req, res, next) {
  const upstreamBase = pickSdkUpstream(req.path)   // 3DS / card / static / icons / SDK
  const targetUrl = `${upstreamBase}${normalizePath(req.originalUrl)}`
  const upstream = await fetch(targetUrl, { redirect: 'follow', headers: { /* accept, user-agent */ } })
  if (upstream.status === 404) return next()
  res.status(upstream.status)
  for (const h of ['content-type', 'cache-control', 'etag', 'last-modified']) {
    const v = upstream.headers.get(h)
    if (v) res.set(h, v)
  }
  upstream.body.pipe(res)   // stream — don't buffer, assets can be big
}

​

7. Handle WebSocket upgrades on the http.Server

const wsProxy = httpProxy.createProxyServer({ changeOrigin: true, ws: true })
const server = app.listen(PORT)
server.on('upgrade', (req, socket, head) => {
  const target = pickWsTarget(req.url)   // BACKEND_WS_URL or SDK_UPSTREAM
  wsProxy.ws(req, socket, head, { target })
})

​

8. Wire up environment variables

• SDK services follow <service>[.<env>].y.uno: sdk-web.y.uno, sdk-web.staging.y.uno, sdk-web.dev.y.uno.
• API surface uses api[-<env>].y.uno: api.y.uno, api-staging.y.uno, api-dev.y.uno. Note the hyphen, not a dot.
• The WebSocket service has no api- prefix; it’s <env>.y.uno directly (y.uno, staging.y.uno, dev.y.uno).

​

9. Ship a minimal landing page

​

Pitfalls and edge cases

• Route order matters. The SDK catch-all is registered last. Anything you app.use after it never runs.
• CORS authority must be the proxy. Letting upstream access-control-* headers through means credentialed cross-origin requests randomly fail when the upstream’s allow-list does not include localhost.
• Hop-by-hop headers are bidirectional. Strip them on both legs. content-length is the one that bites.
• Body consumption is a one-shot. Once express.json() parses a request, the underlying stream is drained. Re-serialize from req.body if you need to forward a POST.
• Streaming, not buffering, for assets. upstream.body.pipe(res) keeps memory flat even for multi-MB bundles.
• Version normalization is SDK_UPSTREAM-only. Card and 3DS micro-apps have their own version segments; rewriting them breaks the upstream URL. The static / icons CDNs aren’t versioned, so they aren’t normalized either.
• Static CDN assets are host-swapped too. Recent SDK builds rewrite their hard-coded icons.prod.y.uno / sdk.prod.y.uno asset URLs onto the white-label host, so the proxy must forward /icons, /css, /brands, /c2p → sdk.prod.y.uno and /sdk-web, /flags, bare /*.png → icons.prod.y.uno. Older SDK builds load these straight from the CDN and never reach the proxy. Exercising this end-to-end needs a recent SDK build and a partner page that inits with { apiUrl: '<proxy origin>' } (or assetUrl).
• Don’t forward the partner page’s cookies to the API. Strip Cookie on /v1//v2 forwards. The browser’s localhost cookies (session, analytics, URL-valued ones like spage) don’t belong on a cross-origin call to api.y.uno and can trip the upstream WAF with a 403. The API authenticates via the public API key.
• WebSocket auth is whatever headers http-proxy sees. Do not strip cookie or authorization from WS upgrades; the cookie strip applies only to the HTTP /v1//v2 backend forwards.
• .env is gitignored. Always keep .env.example in sync; it is the spec for anyone cloning the repo.

​

Verification checklist

1. Network tab: no requests to any *.y.uno host originate from the merchant page. All traffic is to the proxy origin.
2. window.SdkPayments is defined; window.Yuno is either undefined or a legacy alias.
3. sdk-payments-ready event fires on document after the SDK boots.
4. No yuno-* DOM tokens in the rendered output, except for the trust-mark allow-list (yuno-badge, secure-by-yuno, yuno-typography-provider, yuno-c2p, yuno-redirect, yuno-debug, data-yuno-session-id).

​

Reference implementation

​

See also

• White Label (Web SDK): the SDK-side overrides this harness verifies.
• yuno-payments/yuno-sdk-web/tree/main/white-label-proxy-server: full source.
• RFC 7230 §6.1: Connection-specific headers
• http-proxy WebSocket docs