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

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	Include inactive products when resolving options

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 the request's X-API-Version is 2026-09-16 or later; it becomes the default for all requests on 2027-01-11.

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 and cost are returned on all priced items. rrp is included when a recommended retail price is configured for the product. All three fields are omitted from the response when null. 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

{
  "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.