IIMMPACT Catalog SDK

React wrapper for the hosted IIMMPACT catalog checkout experience.

This follows the same industry pattern used by Plaid Link and Stripe Embedded Checkout:

1. The client backend creates a short-lived bootstrap token using HMAC credentials.
2. The client frontend passes that token to this React wrapper.
3. The wrapper opens the hosted catalog UI in a sandboxed iframe.
4. The hosted UI exchanges the bootstrap token and runs catalog and order calls internally.
5. The hosted UI reports payment handoff, exit, event, or error callbacks to the parent app.

HMAC credentials must never be sent to the browser.

Install

npm install @iimmpact-sdn-bhd/catalog-sdk

The package has React as a peer dependency:

npm install react react-dom

React usage

import { CatalogLink } from '@iimmpact-sdn-bhd/catalog-sdk'

export function CheckoutButton() {
  const bootstrapToken = 'token-from-your-backend'

  return (
    <CatalogLink
      bootstrapToken={bootstrapToken}
      widgetUrl="https://catalog.iimmpact.com"
      onSuccess={(result) => {
        console.log('Catalog checkout completed', result.orderId)
      }}
      onExit={({ reason }) => {
        console.log('Catalog checkout closed', reason)
      }}
      onError={(error) => {
        console.error('Catalog checkout failed', error.message)
      }}
    >
      {({ open, status }) => (
        <button disabled={status === 'loading'} onClick={open} type="button">
          Open catalog
        </button>
      )}
    </CatalogLink>
  )
}

Backend bootstrap-token flow

Your backend creates the bootstrap token with HMAC signing:

POST /v2/sdk/catalog/sessions
Content-Type: application/json
X-Api-Key: <client api key>
X-Timestamp: <unix timestamp>
X-Nonce: <unique nonce>
X-Signature: v1=<base64 hmac signature>

{
  "platform": "web",
  "user_id": "customer-123",
  "ic_number": "900101101234",
  "phone_number": "60123456789",
  "name": "Jane Customer",
  "email": "[email protected]"
}

Return only the short-lived session_token to your frontend. Do not return the HMAC secret.

platform, user_id, ic_number, and phone_number are required. name and email are optional.

Hosted UI configuration

The hosted catalog app must be deployed with the client origins that are allowed to embed it:

VITE_CATALOG_SDK_ALLOWED_ORIGINS=https://client.example.com,https://staging-client.example.com

Messages from other origins are ignored.

Build outputs

npm run build:hosted
npm run build:sdk

• dist/ contains the hosted Vite app.
• dist/sdk/ contains the npm package bundle and TypeScript declarations.

Verification

npm test
npm run build
npm audit --audit-level=moderate

Security model

• HMAC signing stays server-side.
• Browser receives only a short-lived bootstrap token.
• Hosted UI receives the token through postMessage after origin validation.
• The iframe is sandboxed and the npm wrapper exposes only callbacks.
• Success callbacks return payment handoff metadata, not credentials or bearer tokens.

Local development

npm install
npm run dev

For staging E2E checks, configure .env from .env.example and use the SDK host test route at /__sdk-host-test.