Merchant API
Checkouts

Create a Hosted Checkout

Create a Hosted Checkout with a minimal Merchant request. Checkout collects an omitted payment method and payer details, or immediately advances a supplied `payment_method` to its authoritative Provider action. The response returns an Init-controlled `checkout_url`; `return_url` is always the Merchant's final return URL.

POST
/checkouts

Create a Hosted Checkout with a minimal Merchant request. Checkout collects an omitted payment method and payer details, or immediately advances a supplied payment_method to its authoritative Provider action. The response returns an Init-controlled checkout_url; return_url is always the Merchant's final return URL.

Authorization

apiKey
AuthorizationBasic <token>

Merchant API key pair. Send as Authorization: Basic base64(publicKey:secretKey) — username is the public key (pk_live_… / pk_test_…), password is the secret key (sk_live_… / sk_test_…). The public key prefix determines the environment of every order created by the request — there is no body, query, or header override.

In: header

Header Parameters

Idempotency-Key*string

Merchant retry identity for this create request. Reuse only with the exact same request fields.

Match^[!-~]+$
Length1 <= length <= 255

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Create a Hosted Checkout. When payment_method is omitted, Checkout collects the method and required payer data; when supplied, Operational Configuration freezes the route and Checkout presents the resulting Provider action.

amount*string

Positive integer amount in the currency's minor units, encoded as a string to preserve precision (e.g. "10000" for MYR 100.00).

Match^[1-9]\d*$
cancel_url?string

Optional Merchant URL used when the Hosted Checkout is cancelled.

Formaturi
Lengthlength <= 2048
country*string

ISO 3166-1 alpha-2 country code, e.g. "MY".

Match^[A-Z]{2}$
currency*string

ISO 4217 currency code (e.g. "MYR", "USD") or a 3–6 letter token symbol. Uppercase.

Match^[A-Z]{3,6}$
customer?

Customer identity. Required fields vary by routed payment method.

merchant_reference*string

Unique Merchant business reference for the Payment created by this Checkout. Transport retries use Idempotency-Key.

Length1 <= length <= 256
metadata?
payment_method?string

Optional Provider-neutral payment method to freeze before opening Hosted Checkout. When omitted, Checkout collects the method from the payer.

Value in

  • "FPX"
  • "PROMPTPAY"
  • "TRUEMONEY"
  • "BANK_TRANSFER"
  • "TNG"
  • "BOOST"
  • "CARD"
  • "GRABPAY"
  • "ALIPAY"
  • "UMOBILE"
  • "EMONEI"
  • "DUITNOW_QR"
  • "WECHAT_PAY"
  • "UNIONPAY"
payment_method_options?

Flat canonical options for the selected payment_method. Required fields are determined by the resolved payment route; FPX accepts only an optional bank.

return_url?string

Optional Merchant final return URL used after Hosted Checkout finishes. It is distinct from every internal Provider return URL.

Formaturi
Lengthlength <= 2048

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/checkouts" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "amount": "string",    "country": "string",    "currency": "string",    "merchant_reference": "string"  }'
{  "amount": "10000",  "checkout_url": "https://checkout.example/pay/dord_01K2VK4V0C7Y6HG4H3ED4HPR2F",  "country": "MY",  "created_at": "2026-08-16T10:00:00.000Z",  "currency": "MYR",  "environment": "test",  "expires_at": "2026-08-16T10:15:00.000Z",  "failure_code": null,  "failure_message": null,  "id": "hchk_01K2VK4V0C7Y6HG4H3ED4HPR2F",  "merchant_reference": "order-2026-08-16-0001",  "object": "checkout",  "payment_intent_id": "dord_01K2VK4V0C7Y6HG4H3ED4HPR2F",  "payment_status": "requires_payment_method",  "processing_stale_at": null,  "status": "open",  "updated_at": "2026-08-16T10:00:00.000Z"}

Get a Hosted Checkout GET

Return a Hosted Checkout and the public status of its canonical Payment. The Checkout URL remains Init-controlled.

List payment intents GET

List payment intents for the authenticating merchant in the key's environment, ordered most-recent-first. Walk pages via `next_cursor`. Filters narrow the set; cursor and filters are independent; apply the filters again on each page request.