Step 2: Calculate Order

Calculate a quote before customer confirmation; this creates no resource and does not lock prices.

Calculate before payment

Calculate before each new payment attempt, including retries after a failed payment. Show the latest total to the customer and use it as expected_payment_total when creating the payment.

Endpoint

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

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.

Request fields

Field	Type	Required	Description
order_id	string	Conditional	Send for an existing unpaid order. Omit items.
items	array	Conditional	Send for a new order. Include at least one item and omit order_id.

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.

Choose one input

Send either items or order_id, not both. With order_id, Pine Labs uses that order's stored items and prices. Keep the payment method and customer fee percent in the request.

The item fields below apply when sending items.

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.

Fee fields

Payment Methods returns each method's fee rule. Calculate Order returns the exact fee and total for the selected method and order.

Field	Type	Description
fee.type	string	fixed or percentage.
fee.value	string	Two-place decimal string: MYR amount for fixed, or percentage from 0.00 to 100.00 for percentage. For example, 1.70 means RM1.70 or 1.70%, respectively.

Customer fee percent

Send the percentage of the payment fee your customer bears on each calculation, order creation, and payment creation request. It is not inherited from an earlier request. Omission means 0.00: you pay the full fee.

{
  "customer_fee_percent": "50.00"
}

Fee calculation

1. Round each server-resolved unit sale price half-up to cents; multiply by quantity and sum the lines.
2. Calculate the payment fee once: for percentage, round subtotal × value / 100 half-up to cents; for fixed, use value as the MYR fee.
3. Customer fee = payment fee × percent / 100, rounded half-up to cents.
4. Your fee = payment fee − customer fee. Payment total = item subtotal + customer fee.

There is no gross-up. The same sharing rule applies to both fee types:

RM100 of items	Customer percent	Customer fee	Your fee	Payment total
1.70% fee (RM1.70)	Omitted	RM0.00	RM1.70	RM100.00
1.70% fee (RM1.70)	50%	RM0.85	RM0.85	RM100.85
1.70% fee (RM1.70)	100%	RM1.70	RM0.00	RM101.70
Fixed RM2.00 fee	Omitted	RM0.00	RM2.00	RM100.00
Fixed RM2.00 fee	50%	RM1.00	RM1.00	RM101.00
Fixed RM2.00 fee	100%	RM2.00	RM0.00	RM102.00

Payment creation checks expected_payment_total against the current calculation. Fees are frozen only when that payment is admitted; refunds do not change its original fee breakdown.

Request example — new order

{
  "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
    }
  ]
}

Request example — existing order

Replace items with order_id and call the same endpoint:

{
  "order_id": "ord_example",
  "payment_method_code": "CARD",
  "customer_fee_percent": "50.00"
}

Response fields

Both inputs return the same calculation breakdown. Existing-order responses also identify the order:

Field	Type	Description
data.order_id	string	Returned when the request includes order_id; omitted for a new-order calculation.

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 — 200

{
  "data": {
    "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"
    }
  }
}

Errors

HTTP	Code	Action
400	validation_error	Fix invalid fields and try again. Sending both items and order_id, or neither, is rejected. See field errors.
400	invalid_items	One or more items failed product validation; error.details.items lists each failure's index, code, and message. Correct them and calculate again.
400	payment_method_unavailable	Refresh methods and choose an available one.
404	order_not_found	The supplied order_id was not found in your account.

See shared errors. After confirmation, create the order or create a new payment for an existing unpaid order.