Catalog SDK Error Handling

Catalog SDK integrations should handle three outcomes: payment handoff, user exit, and error. Treat each checkout attempt as a short-lived session and create a new token when the user retries after a failure or long delay.

Recommended Callback Handling

<CatalogLink
  bootstrapToken={bootstrapToken}
  widgetUrl="https://catalog.iimmpact.com"
  onSuccess={(payload) => {
    startClientPayment({
      orderId: payload.orderId,
      amount: payload.totalAmount,
      items: payload.items,
    });
  }}
  onExit={({ reason }) => {
    if (reason === "client_closed") {
      return;
    }

    console.log("Catalog exited", reason);
  }}
  onError={(error) => {
    reportCatalogError(error);
    showRetryMessage(error.message);
  }}
/>

Common Scenarios

Scenario	What You See	Recommended Action
Catalog order is ready for payment	onSuccess({ orderId, status, totalAmount, items })	Start payment in the client app, then confirm payment from your backend
Payment confirmed	POST /v2/sdk/catalog/orders/{orderId}/payment returns status: "processing"	Only call after backend payment verification; treat response as fulfillment queued, not final transaction success
User closes modal	onExit({ reason: "client_closed" })	Keep the user on the current page
Token expired	onError with an auth/session message	Create a new backend session and retry
Origin not allowlisted	Hosted catalog session requests fail from the browser	Add the exact frontend origin in the IIMMPACT dashboard
Wrong widgetUrl	Iframe fails to load or no ready event arrives	Use https://catalog.iimmpact.com unless IIMMPACT gives you another URL
Network interruption	Hosted UI reports an error or stalls	Show retry and create a fresh token if needed
Payment/catalog failure	onError({ message, code })	Show a user-safe message and log code for support
Fulfillment timeout	Order status becomes timeout	Check transaction history and reconcile using payment_reference

Retrying Safely

For a retry, create a new bootstrap token instead of reusing an old one.

async function refreshAndRetry() {
  const response = await fetch("/api/catalog-session", { method: "POST" });
  const data = await response.json();
  setBootstrapToken(data.session_token);
}

This avoids edge cases where a token expired while the user was idle or after a previous checkout attempt.

Troubleshooting Checklist

The button renders but the modal does not open

• Confirm your render prop calls open from the controller
• Confirm bootstrapToken is a non-empty string
• Check browser console errors from your React app

The iframe opens but stays blank

• Confirm widgetUrl is https://catalog.iimmpact.com
• Confirm the user's network can reach the hosted URL
• Check whether browser extensions or corporate policies block iframes

The iframe opens but callbacks do not fire

• Confirm your frontend origin was added in the IIMMPACT dashboard
• Confirm you are not changing protocols or subdomains between environments
• If you supplied allowedOrigins, confirm it includes the exact hosted widget origin

The hosted UI says the session is invalid

• Create the bootstrap token immediately before opening the catalog
• Do not cache tokens across users or browser sessions
• Confirm the session request includes platform, user_id, ic_number, and phone_number
• Verify backend HMAC signing uses the correct API key, secret, timestamp, nonce, and body hash

Payment confirmation succeeds but the order is not completed yet

• This is expected while the order status is processing
• Fulfillment workers create and check the underlying transactions asynchronously
• Use order status, transaction history, or configured Catalog SDK Webhooks for the final outcome

Logging Guidance

Log enough information for support without exposing secrets:

onError={(error) => {
  logger.warn("Catalog SDK error", {
    code: error.code,
    message: error.message,
  });
}}

Do not log API keys, HMAC secrets, raw signatures, or full bootstrap tokens.

User Messaging

Show user-friendly messages and keep technical details in logs.

Technical Issue	User Message
Expired token	"Your catalog session expired. Please try again."
Network error	"We could not load the catalog. Check your connection and try again."
Product/order error	"We could not complete this request. Please try again or contact support."
Origin/config issue	"Catalog checkout is temporarily unavailable."
Processing fulfillment	"Your payment was received. We are processing your order."