Skip to content
Last updated

Branded SDK quickstart

The branded SDK gives your wallet ready-made reward screens while your backend continues to submit purchases and handle reward outcomes. Follow the initialization, session endpoint and proxy setup below to display those screens for an active cardholder and their group. See the branded rewards quickstart for the underlying purchase and reward flow.

The SDK reports user activity within its screens on your behalf. Send activity separately for experiences you build outside the SDK.

Initialize the SDK

Mount the SDK in a container that stays on the page.

import { Percents } from '@percents/web-sdk';

const widget = Percents.init({
  container: '#percents-widget',
  sessionEndpoint: '/api/percents/session',
  view: 'offers',
  appearance: {
    displayName: 'Branded Rewards',
    primaryColor: '#0079d2',
    accentColor: '#028a00',
    fontFamily: "Gilroy, 'Gilroy Regular', ui-sans-serif, system-ui",
  },
});

widget.on('merchant_activation_completed', (payload) => {
  console.log('Merchant activated', payload);
});

Session Endpoint

sessionEndpoint is owned by the issuer. It authenticates the current user, resolves the active cardholder and group, mints or retrieves a proxy session, and returns:

{
  "widgetUrl": "https://widgets.percents.com/embed/index.html",
  "proxyApiBaseUrl": "https://issuer.example.com/api/percents/proxy",
  "proxySessionToken": "opaque-session-token",
  "expiresAt": "<RFC3339 expiration timestamp>"
}

Store the proxy session and its upstream widget token only on the issuer server. Use a shared, durable session store when the proxy runs on more than one instance.

Server-Side Identity Initialization

The session mint operation lets your backend select the active cardholder as well as their group after authenticating the user.

Choose exactly one request shape:

  • Existing Percents identities: { issuerId, cardholderId, chgId }, using ch_ and chg_ IDs.
  • Your own identities: { issuerId, externalCardholderId, externalCardholderGroupId? }.

Do not mix the two shapes. In the external-ID flow, the mint can create a missing cardholder or group, but never a card. An omitted group reuses the existing assignment or creates a single-cardholder group whose external ID equals externalCardholderId. An assigned cardholder cannot move groups. See lazy provisioning.

Keep the returned cardholderId, chgId and any lazilyProvisionedAccounts mappings on your server with the widget token. Provisioning mappings contain only newly created cardholders or groups. Do not add identity fields to the browser bootstrap.

Widget activity must use the session's active cardholder. Never choose another member of the group or use an ID supplied by the browser.

Proxy API

The iframe calls the issuer proxy with Authorization: Bearer <proxySessionToken>. The proxy validates the session, enforces the active cardholder and group scope, forwards the request to Percents, and strips any server-only credentials from browser-visible responses.

Before minting, register your trusted HTTPS JWKS URL and expected audience with Percents, and coordinate enablement of the issuer-owned registration.

For each mint:

  1. Sign a fresh RS256 assertion with a lifetime of at most 60 seconds.
  2. Set JWT iss and request body issuerId to the exact Percents issuerId from onboarding.
  3. Include exactly the selected identity fields in both the assertion and body. Match every value and the presence or absence of optional externalCardholderGroupId.

Percents verifies the JWT using the registered JWKS before identity lookup or provisioning, then checks issuer ownership and cardholder membership. The widget token binds the issuer, active cardholder and group. Attribute requests to that cardholder and reject mismatches or revoked membership. Obtain a new proxy session and widget token for a new login or active cardholder. See SDK Authentication for the required request, claims, and registration details.

Sandbox Testing

For sandbox testing, deploy an issuer proxy that forwards to https://sandbox.percents.com. Do not point the browser directly at Percents or embed a long-lived API token in the page.