Step 3: Create Order

Create the confirmed purchase and freeze its item prices. No payment starts.

Endpoint

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

Request headers

Field	Type	Required	Description
X-Api-Key	string	Yes	Your API key; keep it on your backend.
X-Timestamp	string	Yes	Current Unix time in seconds; within five minutes of server time.
X-Nonce	string	Yes	Fresh identifier for every request, including retries.
X-Signature	string	Yes	v1= followed by the request's HMAC signature.

Follow API Key Authentication. Sign the exact body, or an empty body for bodyless requests, and the sorted query when present.

Field	Type	Required	Description
Content-Type	string	Yes	application/json.
Idempotency-Key	string	Yes	Unique creation key; follow retry rules.

Request fields

Field	Type	Required	Description
external_reference	string	Yes	Your order reference; unique within your account.
items	array	Yes	Products to purchase. Include at least one item.
metadata	object	No	Additional information as string-to-string entries.

Field	Type	Required	Description
payment_method_code	string	Yes	Code from Payment Methods.
customer_fee_percent	string	No	Percentage of the fee the customer bears, 0.00–100.00; defaults to 0.00.

Method and customer fee percent provide the current calculation only. They do not bind future payments; payer identity, card input, and return URL belong to payment creation.

Item fields

See Product Listing for available products. Each item follows Make Payment — Request Body; IIMMPACT submits its topup after payment succeeds.

Field	Type	Required	Description
items[].product	string	Yes	Product code from Product Listing.
items[].account	string	Yes	Recipient's account number or identifier, such as a bill account or mobile number.
items[].amount	string or number	Yes	Amount for one topup. Required for every product; follows the existing Make Payment rules.
items[].quantity	integer	No	Number of topups for this item; defaults to 1. Must be positive.
items[].remarks	string	No	Additional remarks.
items[].extras	object	Conditional	Additional fields required by the selected product; see Make Payment above.

Order limit

Each order supports up to 100 topups in total. Add the quantities of all items; the total must not exceed 100. An omitted quantity counts as 1.

For example, 10 items with quantity 10 reaches the limit. This limit is checked during calculation and order creation.

Use subproducts where required and bill presentment for bill validation. IIMMPACT generates a transaction reference for each topup and calculates the sale price from the item details.

Request example

{
  "external_reference": "ORD-00042",
  "payment_method_code": "CARD",
  "customer_fee_percent": "50.00",
  "items": [
    {
      "product": "TNB",
      "account": "220012345679",
      "amount": "60.00",
      "quantity": 1
    },
    {
      "product": "TNB",
      "account": "220012345678",
      "amount": "40.00",
      "quantity": 1
    }
  ]
}

Response fields

The response matches calculation, with only order_id added. Values reflect creation-time prices and fees; payment creation checks the confirmed total again before charging.

Field	Type	Description
data.order_id	string	Save for payment creation and order reads.

Field	Type	Description
data.currency	string	MYR.
data.payment_method_code	string	Selected method.
data.customer_fee_percent	string	Percentage of the fee the customer bears, 0.00–100.00.
data.fee	object	Fee rule.
data.items	array	Item details with resolved prices below.
items[].amount	string	Requested topup amount, returned as a two-place decimal string.
items[].unit_price	string	Two-place sale price per unit; may differ from face value.
items[].subtotal	string	Unit price × quantity.
data.totals	object	Two-place amounts below.
totals.items_subtotal	string	Sum of item sale subtotals.
totals.fee	object	The payment fee split between customer and you.
totals.fee.total	string	Full payment fee.
totals.fee.customer	string	Customer's portion of the fee.
totals.fee.merchant	string	Your portion of the fee.
totals.payment_total	string	Item subtotal plus customer fee; use as expected_payment_total.

Response example — 201

{
  "data": {
    "order_id": "ord_example",
    "currency": "MYR",
    "payment_method_code": "CARD",
    "customer_fee_percent": "50.00",
    "fee": {
      "type": "percentage",
      "value": "1.70"
    },
    "items": [
      {
        "product": "TNB",
        "account": "220012345679",
        "amount": "60.00",
        "quantity": 1,
        "unit_price": "60.00",
        "subtotal": "60.00"
      },
      {
        "product": "TNB",
        "account": "220012345678",
        "amount": "40.00",
        "quantity": 1,
        "unit_price": "40.00",
        "subtotal": "40.00"
      }
    ],
    "totals": {
      "items_subtotal": "100.00",
      "fee": {
        "total": "1.70",
        "customer": "0.85",
        "merchant": "0.85"
      },
      "payment_total": "100.85"
    }
  }
}

Errors

HTTP	Code	Action
400	idempotency_key_required	Supply a creation key.
409	idempotency_conflict	This key was already used with different request data. Retry with the original data, or use a new key for a new request.
409	duplicate_external_reference	Use the existing order identified by error.details.order_id.
422	validation_error	Correct field errors.
422	payment_method_unavailable	Refresh methods and choose an available one.

Duplicate-reference details

Field	Type	Description
error.details.order_id	string	Existing order ID within your account.
error.details.external_reference	string	The duplicated order reference.

See shared errors.

Next: Create Payment.