Options API

Returns selectable items for select fields defined in the Catalog API. This is a unified endpoint — all product types use the same request/response structure.

Migrating from /v2/subproducts?

See the Migration Guide for field renames and a checklist.

Endpoint

GET https://api.iimmpact.com/v2/options

Headers

Header	Description	Required
X-Api-Key	Your API key	Yes
X-Timestamp	Unix timestamp in seconds	Yes
X-Nonce	Unique request identifier	Yes
X-Signature	HMAC-SHA256 signature (v1=...)	Yes
X-API-Version	Contract version date, e.g. 2026-09-16 (see Versioning)	No

See API Key Authentication for signing details.

Query Parameters

Parameter	Type	Required	Description
product_code	string	Yes	Product code (e.g., D, HI, JOMPAY)
field_id	string	Yes	Field identifier from catalog (e.g., amount, plan, biller)
account_number	string	Conditional	Required by many dynamic fields (phone number, NRIC, etc.)
biller_code	string	No	Filter by specific biller code (JomPAY only)
limit	number	No	Items per page (default: 100, max: 25,000)
per_page	number	No	Alias for limit
page	number	No	Page number for pagination (default: 1)
is_active	boolean	No	Filter active status (applies to static options)
include_hidden	boolean	No	Include hidden products when resolving options
include_inactive	boolean	No	Resolve options for globally inactive products

Products your account is restricted from purchasing are not resolved: /options returns 404 product-not-found for them, and /catalog does not list them. A static field whose options are all disabled for you returns an empty items list.

Example Request

curl -X GET "https://api.iimmpact.com/v2/options?product_code=D&field_id=amount" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Timestamp: 1704067200" \
  -H "X-Nonce: req-1704067200-a1b2c3d4e5f6" \
  -H "X-API-Version: 2026-09-16" \
  -H "X-Signature: v1=BASE64_HMAC_SIGNATURE"

Response

{
  "product_code": "D",
  "field_id": "amount",
  "items": [
    {
      "code": "30",
      "label": "RM 30",
      "price": { "amount": "30.00", "currency": "MYR" },
      "cost": { "amount": "29.2500", "currency": "MYR" },
      "denomination": 30
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 100,
    "total": 5
  }
}

Field	Type	Description
product_code	string	Echoed product code
field_id	string	Echoed field identifier
items	array	List of selectable items
meta	object	Pagination metadata

Item Schema

Items have a consistent base structure with optional fields depending on product type:

Field	Type	Description	Present For
code	string	Stable identifier for fulfillment	All items
denomination	number	Face value or quantity sent as the payment amount; distinct from customer-facing price.amount	Options belonging to a role: "pricing", type: "select" field
label	string	Display text. For eligible Mobile Data Plan options, Plan Validity is removed from label and returned separately in validity.	All items
validity	string	Plan Validity, e.g. 7 days, 30 days	Mobile Data Plan options when available
features	array	Plan feature labels, e.g. included quota, validity, or pass name	Mobile Data Plan options when available
description	string	Additional details	Optional
price	Money	Effective selling price after reseller adjustments	Priced items
cost	Money	Your wholesale cost	Priced items
rrp	Money	Recommended retail price	Optional
has_loss_risk	boolean	true when adjustment can produce a loss	Priced items
account_number	string	Account identifier for fulfillment	PTPTN accounts
min_amount	Money	Minimum payment amount	JomPAY billers
max_amount	Money	Maximum payment amount	JomPAY billers

Money objects have { "amount": "30.00", "currency": "MYR" } shape.

denomination is a JSON number, not a Money object. It is the face value or quantity to send as amount, distinct from price.amount, and is returned only for options of a pricing select field. Reference and account selectors do not receive it, even when an option code looks numeric. Returned when you send X-API-Version: 2026-09-16; it becomes the default for all requests on 2027-01-11. See Versioning.

Versioning

X-API-Version takes a date (YYYY-MM-DD). Dates later than tomorrow (UTC) and malformed values are ignored, and the current default contract is used. Option denomination is part of the 2026-09-16 release, so until 2027-01-11 send X-API-Version: 2026-09-16. The same header applies to GET /v2/catalog.

Pricing Fields

Three pricing fields support flexible pricing strategies:

• cost — Your wholesale cost (what you pay us). B2B only — do not expose to end users.
• rrp — Recommended retail price (our suggested selling price)
• price — Effective selling price after your reseller adjustment rules

For eligible Mobile Data Plan options, Plan Validity is returned separately in validity when available. Some Mobile Data Plan options, including Hotlink Internet (HI) plans, also return features as an array of display labels describing the plan. The code remains unchanged for fulfillment.

Example Mobile Data Plan option:

{
  "code": "Pantas RM10 10GB 7D",
  "label": "Pantas RM10 10GB",
  "validity": "7 days",
  "price": {
    "amount": "10",
    "currency": "MYR"
  },
  "cost": {
    "amount": "9.7000",
    "currency": "MYR"
  },
  "rrp": {
    "amount": "10",
    "currency": "MYR"
  },
  "has_loss_risk": false,
  "features": ["Pantas RM10 10GB", "7D"],
  "denomination": 10
}

price, cost and rrp are returned on options of pricing fields, and omitted when null. rrp is the configured recommended retail price; when none is configured it is the larger of cost and the face value (denomination × the product's denomination unit price). price is your explicit option rrp if set, otherwise rrp with your product price adjustment applied (a percentage adjustment multiplies, a fixed adjustment adds). See Product Examples for complete responses per product type.

Pagination

For large lists (e.g. JomPAY with 21,000+ billers), use limit and page. Iterate until current_page equals last_page.

TIP

Generate fresh auth headers (timestamp, nonce, signature) for each paginated request.

Caching Large Lists

For JomPAY billers and similar large reference lists, cache the full list locally and refresh daily. This reduces API calls and improves lookup speed.

Error Responses

400 — Missing Parameters

{
  "message": "The given data was invalid.",
  "errors": {
    "product_code": ["The product_code field is required."],
    "field_id": ["The field_id field is required."]
  }
}

400 — Missing Account Number

When a dynamic field requires account_number:

{
  "message": "The given data was invalid.",
  "errors": {
    "account_number": [
      "This field depends on phone and requires account_number parameter."
    ]
  }
}

404 — Invalid Product or Field

Returned for an unknown product or one your account cannot purchase (Product '<code>' not found), and for a field with no options source:

{
  "message": "Options not found for INVALID/amount",
  "errors": {}
}

Product-Specific Examples

See Catalog Product Examples for complete end-to-end flows showing catalog fields, options responses, and resulting payment requests for each product type.