Dynamic Product Catalog

Preview

This API is active and recommended for new integrations. The schema may evolve before general availability.

Overview

The Dynamic Product Catalog introduces a backend-driven product configuration model. Instead of hardcoding product flows in your application, products are defined as purchase forms where fields, validation, options, and checkout mapping are fully configurable from the backend.

Tenant-Specific Catalog

The catalog returned by /v2/catalog is unique to each tenant. Through the IIMMPACT Dashboard, you can:

View your costs — See wholesale pricing for each product
Set price adjustments — Configure fixed or percentage adjustments per product
Customize your catalog — Create custom groups, categories, and product ordering
Enable/disable products — Choose which products to offer your users

This means the API returns your personalized catalog with your pricing and structure.

Key Benefits

Benefit	Description
No App Updates	Add or modify products without client releases
Unified Field Model	Inputs, amounts, and selections are all "fields" with consistent handling
Explicit Fulfillment	Clear declaration of how fields map to payment requests
Multi-Tenant Ready	Same schema serves multiple apps with customizable catalogs

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                         Your Application                            │
├─────────────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────────┐   │
│  │ Catalog      │  │ Options      │  │ Dynamic Form Builder     │   │
│  │ Cache        │  │ Fetcher      │  │ (renders fields)         │   │
│  └──────┬───────┘  └──────┬───────┘  └──────────────┬───────────┘   │
│         │                 │                          │              │
│         └─────────────────┴──────────────────────────┘              │
│                              │                                      │
└──────────────────────────────┼──────────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────────┐
│                         IIMMPACT API                                │
├─────────────────────────────────────────────────────────────────────┤
│  GET /v2/catalog              │  GET /v2/options                    │
│  - Returns full product       │  - Returns items for select fields  │
│    catalog with fields        │  - Supports reference & dynamic     │
│  - Cached on device           │  - Paginated for large lists        │
└─────────────────────────────────────────────────────────────────────┘

Endpoints

Endpoint	Purpose
`GET /v2/catalog`	Returns the complete product catalog with hierarchical structure and field configurations
`GET /v2/options`	Returns selectable items for `select` fields (billers, plans, amounts)

Core Concepts

Everything is a Field

The key insight: inputs, amount selection, and option selection are all fields with consistent structure. There are four field types — text, number, select, and money — each with optional validation and input mode hints. See the Catalog API Reference for the full field schema, properties, and validation rules.

Where the pricing data comes from depends on the field type:

select fields require fetching options from /v2/options (fixed amounts, plans, packages)
money fields have min/max validation directly in the catalog response (flexible amounts)

Where Pricing Data Lives

A common question: "Do I need to call the Options API for this product?"

Pricing Model	Field Type	Where Data Lives	Example Products
Fixed amounts	`select`	Options API (`/v2/options`)	Digi Prepaid (RM 5, 10, 30)
Flexible range	`money`	Catalog (`validation.min/max`)	TNB, JomPAY (RM 1 - RM 30,000)
Dynamic plans	`select`	Options API (with `account_number`)	Hotlink Internet, PTPTN

Decision rule: If the pricing field is type: "select", call /v2/options. If it's type: "money", use validation.min/max from the catalog directly.

Pricing

Each product includes a pricing object with your wholesale cost, an optional price adjustment (configured via Dashboard), and a loss risk flag. This is B2B data for your backend margin calculations — do not expose to end users. See the Catalog API Reference for cost models, adjustment types, and calculation examples.

Fulfillment

Each product declares a fulfillment object that maps form fields to the POST /v2/topup payment request (account, amount, extras). You still provide your own refid and optional remarks. See the Catalog API Reference for the full mapping spec.

Quick Start

1. Fetch the Catalog

bash

curl -X GET "https://api.iimmpact.com/v2/catalog" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Timestamp: 1704067200" \
  -H "X-Nonce: req-1704067200-a1b2c3d4e5f6" \
  -H "X-Signature: v1=BASE64_HMAC_SIGNATURE"

2. Render Dynamic Form

For each product, iterate through fields and render appropriate inputs based on type.

3. Fetch Options for Select Fields

When a user interacts with a select field:

bash

curl -X GET "https://api.iimmpact.com/v2/options?product_code=HI&field_id=plan&account_number=0123456789" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Timestamp: 1704067200" \
  -H "X-Nonce: req-1704067200-a1b2c3d4e5f6" \
  -H "X-Signature: v1=BASE64_HMAC_SIGNATURE"

4. Build Payment Request

Use the product's fulfillment mapping to populate product, account, amount, and extras, then add your own refid for idempotency (see Make Payment).

Complete Flow Examples

Fixed Denominations (e.g., Digi Prepaid)

Products with predefined amounts use select fields that require the Options API:

1. GET /v2/catalog
   → Product "D" has a `select` field with role "pricing"

2. GET /v2/options?product_code=D&field_id=amount
   → Returns [RM 5, RM 10, RM 30, RM 50, RM 100]

3. User selects RM 30

4. POST /v2/topup
   → { product: "D", account: "0123456789", amount: "30.00" }

Flexible Amounts (e.g., TNB, JomPAY)

Products with amount ranges use money fields with validation in the catalog:

1. GET /v2/catalog
   → Product "TNB" has a `money` field with validation: { min: 10, max: 60000 }

2. No Options API call needed for the amount field

3. User enters RM 150.00 (validated against min/max)

4. POST /v2/topup
   → { product: "TNB", account: "123456789012", amount: "150.00" }

Dynamic Plans (e.g., Hotlink Internet)

Products with user-specific options use select fields with dependencies:

1. GET /v2/catalog
   → Product "HI" has a `select` field with data_source.depends_on: ["phone"]

2. User enters phone number: 0178855286

3. GET /v2/options?product_code=HI&field_id=plan&account_number=0178855286
   → Returns plans available for this specific number

4. User selects "Unlimited Weekly Pass RM12"

5. POST /v2/topup
   → { product: "HI", account: "0178855286", amount: "12.00", extras: { subproduct_code: "..." } }

What Backend Can Change (No App Update)

Add/remove/reorder groups and categories
Add new products using existing field types
Modify field labels, placeholders, validation
Change denomination options (fixed amounts, min/max)
Update biller lists, payment codes
Enable/disable products

What Requires App Update

New field types (e.g., image_upload, signature)
Breaking schema changes

Webhooks

Register a webhook for real-time catalog change notifications. See the Catalog Webhooks guide for event types, payload format, signature verification, and retry policy.

Dashboard Configuration

The IIMMPACT Dashboard allows you to customize your catalog before it's served via the API.

Pricing Configuration

Setting	Description
View Cost	See your wholesale cost for each product
Price Adjustment	Configure fixed or percentage `price_adjustment` values
Per-Product	Set different adjustment rules by product

Catalog Organization

Setting	Description
Custom Groups	Create your own top-level groups (e.g., "Popular", "Promos")
Custom Categories	Organize products into categories within groups
Product Ordering	Drag-and-drop to reorder products within categories
Enable/Disable	Toggle products on or off for your catalog

Product Visibility

Setting	Description
Active Products	Use `is_active=true` to return enabled only
Hidden Products	Hidden products are excluded unless `include_hidden=true`
New Products	Newly added products are disabled by default

Instant Updates

Changes made in the dashboard are reflected in your /v2/catalog response. If you've registered a webhook, you'll receive per-resource events (for example product.updated).

What's Next

Catalog API Reference — Full endpoint documentation, field schema, pricing models, and product examples
Options API Reference — Options endpoint for select fields
Catalog Webhooks — Real-time catalog change notifications
Migration Guide — Migrating from product-list to catalog

Dynamic Product Catalog ​

Overview ​

Tenant-Specific Catalog ​

Key Benefits ​

Architecture ​

Endpoints ​

Core Concepts ​

Everything is a Field ​

Where Pricing Data Lives ​

Pricing ​

Fulfillment ​

Quick Start ​

1. Fetch the Catalog ​

2. Render Dynamic Form ​

3. Fetch Options for Select Fields ​

4. Build Payment Request ​

Complete Flow Examples ​

Fixed Denominations (e.g., Digi Prepaid) ​

Flexible Amounts (e.g., TNB, JomPAY) ​

Dynamic Plans (e.g., Hotlink Internet) ​

What Backend Can Change (No App Update) ​

What Requires App Update ​

Webhooks ​

Dashboard Configuration ​

Pricing Configuration ​

Catalog Organization ​

Product Visibility ​

What's Next ​