An embedded wallet must show only the signed-in customer's rewards and keep issuer credentials out of the browser. Use the proxy-session, request validation and browser controls below to protect the branded SDK connection. SDK authentication covers how to obtain its scoped session.
The issuer session endpoint returns only the browser-safe bootstrap values:
widgetUrlproxyApiBaseUrlproxySessionTokenexpiresAt
proxySessionToken is an opaque, expiring credential that is valid only at the issuer proxy. It is not a Percents API token and cannot be used directly against Percents.
The issuer proxy must keep the following values server-side:
- The mapped cardholder group (
chgId) and the activecardholderId, issuer identity and provisioning mappings. - The Percents widget token.
- Issuer API credentials and assertion-signing keys.
Do not include any of those values in a browser response, iframe bootstrap message, URL, client-side configuration, or log entry.
Authenticate the current issuer user and select either existing Percents cardholder and group IDs or external IDs on the server. The mint operation verifies the signed assertion before identity lookup or lazy provisioning. It can create a missing cardholder or group, but never a card. The proxy is the source of truth for the user mapping. Do not trust identities supplied by the browser.
The widget token binds the issuer, active cardholder and group. Keep the returned identities and any lazilyProvisionedAccounts mappings server-side. The browser receives only the four fields above.
The proxy must validate the opaque proxy-session token on every iframe request. Invalidate the proxy session and remove its server-side widget token when:
- The session expires.
- The user logs out.
- The user's cardholder group access changes.
- The active cardholder changes or their group membership is revoked.
- The session is suspected to be compromised.
Require the host app to obtain a new proxy session before mounting or continuing the widget. Each new login requires a new proxy session and widget token, even when the group stays the same.
Use a shared, durable server-side session store when the proxy runs on more than one instance. An in-memory store can lose sessions on restart and cannot safely serve requests across instances.
The SDK mounts the widget in a sandboxed iframe. The host page supplies the opaque proxy-session token only after the iframe has loaded.
When receiving postMessage events, accept a message only when both conditions are true:
event.originmatches the configured Percents widget origin.event.sourceis thecontentWindowof the iframe mounted by the SDK.
Treat message data as untrusted until those checks succeed. Do not use wildcard origins or accept messages from an unexpected window. The production SDK bundle is served from a Percents-controlled origin.
Configure the issuer host and proxy with these controls:
- Iframe sandbox: grant only the sandbox permissions required by the widget. The SDK requires scripts, forms, same-origin, and popups. Do not add permissions without a documented widget need.
- CORS: allow only the issuer host application's exact browser origins to call the issuer proxy. Never use
*for authenticated proxy routes. - Framing policy: configure the response
Content-Security-Policyframe-ancestorsdirective so only the issuer's approved host origins can frame the widget. - Transport: serve the host app, issuer proxy, JWKS endpoint, and widget over HTTPS in production.
The issuer proxy authorizes browser requests. For every request, it must:
- Validate the opaque proxy session.
- Resolve the bound issuer, active cardholder, group and server-side widget token from that session.
- Forward only the widget routes explicitly allowlisted by the issuer.
- Send the server-side widget token to Percents. Never forward the browser's proxy-session token upstream.
- Remove upstream credentials and server-only identifiers from the browser-visible response.
Do not implement a general-purpose Percents API relay. Requests outside the widget allowlist must be rejected by the issuer proxy.
Attribute activity to that active cardholder and reject identity mismatches, issuer ownership failures or revoked group membership. A request cannot select another cardholder or move an assigned cardholder to another group. See assertion and identity rules.
Widget activity must use the session's active cardholder, never another group member or a browser-supplied ID.