Catalog SDK Authentication

The Catalog SDK has a two-part authentication model:

Party	Authenticates With	Purpose
Your backend	`X-Api-Key` + HMAC headers	Create catalog bootstrap sessions
Your frontend	`bootstrapToken` only	Open the hosted catalog through `CatalogLink`

The browser never receives your API key, HMAC secret, or signing material.

Session Creation

Your backend creates a catalog session with:

http

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-sha256 signature>

{
  "platform": "web",
  "user_id": "customer-123",
  "ic_number": "900101101234",
  "phone_number": "60123456789",
  "name": "Jane Customer",
  "email": "jane@example.com"
}

The response includes a short-lived session_token. Your backend returns only that token to your frontend.

Session creation requires platform, user_id, ic_number, and phone_number. name and email are optional. IIMMPACT hashes the IC number for storage and links the session to the existing Catalog SDK user with the same user_id, or creates that user when it does not exist yet.

DANGER

HMAC signing must be server-side only. Do not expose X-Api-Key, HMAC secrets, generated signatures, or canonical signing strings in frontend code.

Runtime Flow

Catalog SDK Endpoint Surface

Client integrations need these server-to-server endpoints:

Endpoint	Auth	Called By	Purpose
`POST /v2/sdk/catalog/sessions`	API Key + HMAC	Your backend	Create or update a Catalog SDK user and return a bootstrap token
`POST /v2/sdk/catalog/orders/{orderId}/payment`	API Key + HMAC	Your backend	Confirm verified successful payment and queue asynchronous fulfillment

DANGER

Call POST /v2/sdk/catalog/orders/{orderId}/payment only after your backend has verified that your own payment flow succeeded. This endpoint is the fulfillment trigger and may start the topup or bill payment transaction.

Order statuses are pending_payment, processing, completed, and timeout. Transaction statuses are pending, processing, successful, and failed.

Frontend Origin Allowlist

Add your web app origins in the IIMMPACT dashboard so the hosted catalog can run inside your site and make browser session requests. This applies to the hosted web Catalog SDK flow only; your backend API Key + HMAC requests do not use browser origins.

Add each exact frontend origin you use, for example:

text

https://app.example.com
https://staging.example.com

Origin matching is exact. https://app.example.com does not also allow https://www.app.example.com, https://staging.app.example.com, or http://localhost:3000.

Security Considerations

Concern	Required Practice
Secret leakage	Keep API keys and HMAC secrets on your backend only
Token reuse	Create a fresh bootstrap token for each checkout attempt
Origin mismatch	Add every exact production and staging frontend origin in the IIMMPACT dashboard
Message spoofing	Keep `widgetUrl` pointed at the trusted IIMMPACT-hosted catalog domain
Public environment variables	Do not put secrets in `VITE_`, `NEXT_PUBLIC_`, or other browser-exposed env vars
Payment confirmation	Confirm payment from your backend only after verified successful payment, then track asynchronous fulfillment

Catalog SDK Authentication ​

Session Creation ​

Runtime Flow ​

Catalog SDK Endpoint Surface ​

Frontend Origin Allowlist ​