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; the purchased product runs after payment succeeds.

Field	Type	Required	Description
items[].product	string	Yes	Product code from Product Listing.
items[].account	string	Product-dependent	Recipient's account number or identifier. Send "" only when the product allows an optional account; otherwise provide its required destination. A supplied value must still pass that product's validation.
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. Each purchased unit gets a fulfillment reference and a sale price calculated 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 includes the creation calculation, order_id, and the new-payment admission cutoff. 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.
data.external_reference	string	Your order reference, echoed back.
data.status	string	payment_pending on a new order.
data.created_at	string	UTC order creation time.
data.updated_at	string	UTC time of the latest public change.
data.expires_at	string	UTC deadline for creating payments, 24 hours after order creation.

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[].product	string	Product code.
items[].product_name	string	Product display name.
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",
    "external_reference": "ORD-00042",
    "status": "payment_pending",
    "currency": "MYR",
    "payment_method_code": "CARD",
    "customer_fee_percent": "50.00",
    "fee": {
      "type": "percentage",
      "value": "1.70"
    },
    "items": [
      {
        "product": "TNB",
        "product_name": "Tenaga Nasional Berhad",
        "account": "220012345679",
        "amount": "60.00",
        "quantity": 1,
        "unit_price": "60.00",
        "subtotal": "60.00"
      },
      {
        "product": "TNB",
        "product_name": "Tenaga Nasional Berhad",
        "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"
    },
    "created_at": "2026-09-14T02:00:00.000Z",
    "updated_at": "2026-09-14T02:00:00.000Z",
    "expires_at": "2026-09-15T02:00:00.000Z"
  }
}

Errors

HTTP	Code	Action
400	validation_error	Correct field errors; error.details also covers a missing or malformed Idempotency-Key.
400	invalid_items	One or more items failed product validation; error.details.items lists each failure's index, code, and message.
400	payment_method_unavailable	Refresh methods and choose an available one.
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	idempotency_in_progress	The original request with this key is still being processed; retry the same request after it resolves.
409	duplicate_external_reference	Use the existing order identified by error.details.order_id.

Duplicate-reference details

Field	Type	Description
error.details.order_id	string	Existing order ID within your account.

See shared errors.

Next: Create Payment.