Skip to content

Branded rewards SDK

The optional branded SDK adds ready-made offers, wallet balances and reward activity to your web app. Use the component overview and session flow below to decide what to embed and how your backend connects it to the right cardholder group.

The session contract binds the SDK session to an active cardholder and their group so SDK activity can be reported on the issuer’s behalf. It supports existing Percents IDs or lazy provisioning with your internal IDs. You do not need to submit SDK activity again through the API. Your backend still submits purchases and handles reward webhooks.

Product Scope

The SDK supports branded rewards, including branded merchant activation. For cashback, use the HTTP API and explicitly record cardholder user activity for CLICK and VIEW. SDK merchant activation does not activate cashback.

The playground demonstrates appearance with sample data. It does not process purchases or qualify rewards.

Integration flow

  1. The issuer host app loads @percents/web-sdk and calls Percents.init(...).
  2. The SDK requests a short-lived SDK session from the issuer-owned session endpoint.
  3. The SDK mounts the Percents iframe app and sends the session, appearance, and initial view through postMessage.
  4. The iframe calls the issuer-owned proxy API, which forwards requests scoped to the active cardholder and group to Percents.

The browser receives only an opaque proxy session token that is meaningful to the issuer proxy. It never receives a broad Percents API token.

Components

  • Offers: available branded rewards offers and merchant activation.
  • Wallet: merchant-scoped branded balance summaries and balance detail.
  • History: branded rewards activity and balance trends.

Use the SDK Playground to customize the appearance and see the SDK event stream.