Catalog SDK

The Catalog SDK is a React wrapper for the hosted IIMMPACT catalog checkout experience. It lets your frontend open the product catalog in a secure iframe while keeping API credentials and HMAC signing on your backend.

Use this SDK when you want IIMMPACT to handle catalog browsing, product form rendering, and order creation inside a hosted UI, while your client app owns the final payment step through its own payment rails.

How It Works

1. Your backend creates or updates the Catalog SDK user and creates a short-lived catalog bootstrap token with POST /v2/sdk/catalog/sessions.
2. Your frontend passes that token to CatalogLink from @iimmpact-sdn-bhd/catalog-sdk.
3. The SDK opens https://catalog.iimmpact.com in a sandboxed iframe.
4. The hosted catalog UI exchanges the bootstrap token and performs catalog, product, and order calls internally.
5. The hosted UI returns a payment handoff payload to your client app.
6. Your client app collects payment from the user through your own payment rails.
7. Your backend verifies the payment succeeded in your own system.
8. Only after verification, your backend confirms the payment against the created IIMMPACT order.
9. IIMMPACT fulfills the order asynchronously and can send a Catalog SDK webhook when fulfillment completes.

Package

Platform	Package	Display Mode
React web apps	@iimmpact-sdn-bhd/catalog-sdk	Hosted modal iframe

The package is intentionally thin. It does not contain API credentials or catalog business logic. Catalog browsing and order creation run on IIMMPACT-controlled infrastructure behind the hosted catalog UI; final payment is handled by the client app.

What the SDK Does

• Opens the hosted catalog checkout at https://catalog.iimmpact.com
• Sends your backend-created bootstrap token to the hosted UI with postMessage
• Validates message origins before accepting hosted UI callbacks
• Renders a mobile-first modal iframe with sensible accessibility labels
• Exposes React callbacks for readiness, payment handoff, exit, analytics events, and errors

What the SDK Does NOT Do

• HMAC signing — your backend creates the bootstrap token with API Key + HMAC credentials
• Direct browser API calls with secrets — HMAC secrets must never be bundled into frontend code
• Payment collection — the client app collects payment through its own wallet, banking, card, or internal rails
• Self-hosted catalog logic — product browsing and order creation run in the hosted catalog UI
• Wildcard origin matching — accepted message origins are exact matches only

Environments

Environment	Widget URL	Use For
Production	https://catalog.iimmpact.com	Live customer traffic
Development	https://dev-catalog.iimmpact.com	Integration testing and staging validation

Use the production URL for live integrations. Use the development URL while building and testing the integration.

INFO

Add each web app origin that will embed the hosted catalog in the IIMMPACT dashboard. This allowlist is used by the browser-based Catalog SDK flow, not by your backend API Key + HMAC requests.

Payment Handoff

After the user chooses a product and confirms the order details in the hosted catalog, the SDK calls onSuccess with the data your client app needs to start payment:

interface CatalogSdkSuccessPayload {
  orderId: string;
  status: "pending_payment";
  totalAmount: string;
  items: Array<{
    product_code: string;
    account_number: string;
    amount: string;
    quantity: number;
    extras?: Record<string, unknown>;
  }>;
}

Your client app should then:

1. Use totalAmount to display and collect payment.
2. Keep orderId as the IIMMPACT order reference.
3. Use items to show the selected products, accounts, item amounts, quantities, and extras.
4. Complete payment through your own payment flow.
5. From your backend, confirm the IIMMPACT order as paid using your payment reference only after verifying that payment succeeded in your system.
6. Track fulfillment through order/transaction status or configured Catalog SDK Webhooks.

Do not treat the onSuccess callback as proof that money has been collected. It means the catalog/order step is ready for the client-owned payment step.

Payment confirmation is also not final fulfillment. The confirmation response returns processing while IIMMPACT creates and checks the underlying transactions. The order becomes completed after all transactions reach terminal status.

DANGER

Do not call the payment confirmation endpoint before your payment is actually successful. It queues fulfillment and may trigger the topup or bill payment transaction.

Next Steps

• Quickstart — Install the package and open the catalog from React
• Authentication — Create bootstrap tokens safely from your backend
• React SDK — Component props, callbacks, and headless hook usage
• Webhooks — Receive final order outcome notifications
• Error Handling — Handle exits, expired tokens, and integration issues
• Catalog API reference — Understand the underlying product catalog model