Step 4: Hosted Checkout

Send the customer to an IIMMPACT-hosted page to pay an existing order. The page lists available methods and saved cards, calculates fees, asks the customer to confirm the total, and handles card entry, FPX bank selection and 3DS. You do not build a payment UI or handle card data.

Use this instead of Create Payment. Create the order first with Create Order; its payment_method_code only sets that order's calculation, and the customer can pick another method on the page.

Endpoint

POST https://api.iimmpact.com/v2/checkout-sessions

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 key for this session; reuse it for network retries.

Request fields

Field	Type	Required	Description
order_id	string	Yes	Existing unexpired order in your account.
customer_external_id	string	Yes	Your customer ID, 1–100 characters, matched exactly. The page shows this customer's saved cards.
customer_name	string	Yes	Customer's name, 1–50 characters, no control characters. Pass the name you already hold for the customer, such as from your KYC records; the page does not ask for it.
return_url	string	Yes	Your HTTPS destination after payment, with the same restrictions as Create Payment.
customer_fee_percent	string	No	Percentage of the fee the customer bears, 0.00–100.00; defaults to 0.00. The customer cannot change it.

Unsupported fields return validation_error.

Request example

{
  "order_id": "01J9Z6Q4M8N2P5R7S9T1V3W5X7",
  "customer_external_id": "CUS-1042",
  "customer_name": "Aisha Rahman",
  "return_url": "https://shop.example.com/payment-return",
  "customer_fee_percent": "50.00"
}

Response fields

Fields below are inside data.

Field	Type	Description
session_id	string	Checkout session ID. Not an order or payment ID.
order_id	string	The order this session pays.
hosted_payment_url	string	Page to open for the customer. It contains a secret token: open it only for this customer, and never log or share it.
expires_at	string	When the link stops working, 30 days after creation. New payments still stop at the order's expires_at.

Response example — 201

{
  "data": {
    "session_id": "01J9Z6QBX3D5F7H9K1M3P5R7T9",
    "order_id": "01J9Z6Q4M8N2P5R7S9T1V3W5X7",
    "hosted_payment_url": "https://pay.iimmpact.com/c/01J9Z6QBX3D5F7H9K1M3P5R7T9#st=mpcs_REDACTED",
    "expires_at": "2026-10-14T02:01:00.000Z"
  }
}

Creating a session starts no payment. A payment is created only when the customer confirms the total on the page.

Open the page and handle the return

Redirect the customer's browser, or open a webview, to hosted_payment_url. Each payment attempt on the page follows the usual payment rules: one active payment per order, and a new attempt after a failure. Do not create a custom payment for an order the customer is paying on the hosted page.

After a payment attempt, the page offers a Return to merchant button that opens your return_url with order_id and payment_id added. Those IDs are not proof of payment. Authenticate the customer and read the payment and order, or use webhooks. Payment, order and refund webhooks are the same as for custom payments.

Errors

HTTP	Code	Action
400	validation_error	Fix the fields listed in error.details. See validation details.
404	order_not_found	Check the order ID and access.
409	order_expired	The order no longer accepts payments. Create a new order.
409	idempotency_conflict	This key was already used with different request data. Use a new key for a different session.
409	session_creation_in_progress	Retry the same request and key shortly to get the original response.

See shared errors. Next: Track Results.