Make Payment

Legacy Endpoint Name

The endpoint path /v2/topup is a legacy name. This single endpoint processes all transaction types: mobile reload, bill payments, vouchers, gift cards, eSIM, and more.

Process transactions across the IIMMPACT platform. This is a unified endpoint for all product offerings, including JomPAY, mobile reload, gift cards, vouchers, eSIM purchases, and more.

TIP

For a step-by-step integration walkthrough, see the Make Payment Guide.

Idempotency

The API supports idempotency — you can safely retry requests without creating duplicate transactions. Store and re-use the same refid for the same transaction.

Check Final Transaction Status: Call this API again with the identical request parameters and the original refid used during initiation. The API will return the current status of the transaction.

API Endpoint

POST https://api.iimmpact.com/v2/topup

DANGER

Staging server statuses and failure reasons might not match production due to limited validation.

Request 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 how to sign your requests.

Request Body

Parameter	Type	Required	Description
refid	string	Yes	Your unique reference ID for this transaction. See refid constraints.
product	string	Yes	Product code
remarks	string	No	Optional field for any additional remarks
account	string	Yes	Recipient's account number or identifier (e.g., bill account number, mobile number)
amount	string | number	Yes	Accepts both string and number in the request body. Internally parsed as decimal. The response always returns a number (integer if whole number, decimal otherwise).
extras	object	No	Additional parameters required by specific products (see below)
extras.subproduct_code	string	No	Sub-product code
extras.ic_number	string	No	IC number without dashes
extras.biller_code	string	No	Biller code
extras.ref2	string	Conditional	Required by some JomPAY billers. The ref2 value is typically printed on the user's JomPAY bill. Use bill presentment to validate. The API returns an error if ref2 is required but not provided.

refid Constraints

Constraint	Value
Max length	50 characters
Allowed characters	Any non-empty string
Uniqueness scope	Per reseller account (not global)
Idempotency	Permanent — re-querying with an existing refid always returns the original transaction

Example Request Body

{
  "refid": "321479-0-30f4f209-ee",
  "product": "GC",
  "account": "0123456789",
  "amount": 10.00, // Strings also work, e.g. "10.00"
  "remarks": "",
  "extras": {}
}

Extras Requirements by Product

Parameter	JomPAY	PTPTN	Mobile Data	Others
subproduct_code	-	Mandatory	Mandatory	-
ic_number	Mandatory (payee IC)	Mandatory (recipient IC)	-	-
biller_code	Mandatory	-	-	-
ref2	Conditional	-	-	-

AMLA Compliance — JomPAY

Due to AMLA (Anti-Money Laundering Act 2001) requirements, it is mandatory to perform eKYC (electronic Know Your Customer) on your end-users for all JomPAY transactions. Pass the verified IC number (Malaysians) or Passport number (non-Malaysians) via the ic_number field. Failure to comply, or providing fictitious/invalid numbers, may lead to account suspension.

Response 200

Field	Type	Description
data	object	Transaction result
data.statusCode	number	Status code — see Payment Errors
data.status	string	Outcome: Accepted, Processing, Succesful, or Failed
data.account	string	Account number
data.product	string	Product code
data.productName	string	Product name
data.amount	number	Amount paid
data.sn	string	Serial number from the provider/operator
data.pin	string	PIN for vouchers, gift cards, etc.
data.expiry	string	Voucher expiration date (yyyymmdd)
data.cost	number	Your wholesale cost for this transaction (deducted from your IIMMPACT wallet balance).
data.balance	number	Current wallet balance
data.remarks	string	Additional notes about the transaction
data.refid	string	Your unique reference ID
data.timestamp	string	Transaction timestamp
data.note	string	Instructions or information for the user regarding the product
data.voucherlink	string	Link to access or redeem the voucher

Spelling Note

The success status value is spelled Succesful (single 's'), not Successful. This is a legacy quirk that cannot be changed. Match this exact string in your code.

Example Response:

{
  "data": {
    "statusCode": 20,
    "status": "Succesful",
    "account": "0123456789",
    "product": "GC",
    "productName": "Grab Gift Code",
    "amount": 5,
    "sn": "106648697",
    "pin": "MPHE39G3WL",
    "expiry": "20251116",
    "cost": 5,
    "balance": 50.54,
    "remarks": "",
    "refid": "321479-0-30f4f209-ee",
    "timestamp": "2025-05-20 13:09:34",
    "note": "Insert voucher code into Use Grab Gifts under Use Offers section upon check out",
    "voucherlink": "https://api.grab.com/gifts/v2/go?id=7464957319334bb0afbd5980738a2b50"
  }
}

Transaction Status Values

Status	StatusCode	Description	Retryable
Accepted	0	Transaction accepted, processing will begin	Yes (re-query with same refid)
Processing	1	Transaction is being processed	Yes (re-query with same refid)
Succesful	20	Transaction completed successfully	No
Failed	40-61 (excl. 53)	Transaction failed (see statusCode for reason)	No (use new refid)
Refund	53	Transaction voided and refunded	No

Recommended Polling Strategy

When a transaction returns Processing, poll every 5-10 seconds by re-querying with the same refid. Most transactions resolve within 30 seconds. Always combine polling with callbacks — polling provides immediate UX feedback, while callbacks are the reliable final status delivery mechanism.