Collect API

Create Collect Order

Creates a new collect order.

• Method: POST
• Path: /api/v1/mch/pmt-orders
• The POST body must be JSON

Notes

• currency currently allows PHP, THB, VND, and USDT, in either case
• amount is validated in the range 0 ~ 50000000000
• trans_id must be globally unique
• If channel starts with usdt, the system forces currency to USDT
• If merchant-side collect rate limiting is enabled, the API may return 429

Request Parameters

Parameter	Type	Required	Description
mch_id	integer	Yes	Merchant ID
trans_id	string	Yes	Merchant order ID, must be unique
currency	string	Yes	Currency code. See System Currency Codes
amount	string	Yes	Order amount. Send it as a string, for example \"100.00\"
channel	string	Yes	Channel code. See System Channel Codes
callback_url	string	Yes	Callback URL for collect result. Must be a valid URL
payer_account_no	string	No	Payer account. Used by some real-name or upstream channel flows
payer_account_name	string	No	Payer name
payer_account_org	string	No	Payer institution
mode	string	No	Channel-specific extension parameter
return_url	string	No	Return URL after cashier completion
uid	string	No	Business user ID used by some channels or risk rules
remarks	string	No	Merchant note saved with the order
nonce	string	Yes	Random token, length: 6-24
timestamp	integer	Yes	UNIX timestamp
sign	string	Yes	See Signature Algorithm

Note

Some extension fields are only used in specific business scenarios. If you are unsure whether they are required, confirm with the platform integration contact first.

Response Fields

On success, the response usually contains the following fields:

Field	Type	Description
id	string	Platform order ID
trans_id	string	Merchant order ID
order_amount	string	Order amount
ratio	number	Merchant fee ratio
currency	string	Currency
code	string	Channel code
status	number	Usually 20 on creation
created_at	string	Creation time
url	string	Cashier URL
cashier_type	number	Cashier mode
meta	object | null	Extra receiving data, depending on the channel

cashier_type

Value	Description
0	Only url is returned
1	Only meta is returned
9	Both url and meta are returned

Example

{
  "code": 200,
  "payload": {
    "id": "C202605040001",
    "trans_id": "ORDER-10001",
    "order_amount": "100.00",
    "ratio": 1.2,
    "currency": "VND",
    "code": "bank",
    "status": 20,
    "created_at": "2026-05-04 10:05:00",
    "url": "https://cashier.example.com/cashier/vn/C202605040001",
    "cashier_type": 9,
    "meta": {
      "account_no": "8531112111",
      "account_name": "CHEN MINH HIEU",
      "account_org": "MSB",
      "account_org_code": "970426",
      "remarks": "PAY12345",
      "qr_url": "data:image/png;base64,..."
    }
  }
}

Query Collect Order

• Method: GET
• Path: /api/v1/mch/pmt-orders

Request Parameters

Parameter	Type	Required	Description
id	string	No	Platform order ID. Use either id or trans_id
trans_id	string	No	Merchant order ID. Use either id or trans_id
mch_id	integer	Yes	Merchant ID
nonce	string	Yes	Random token, length: 6-24
timestamp	integer	Yes	UNIX timestamp
sign	string	Yes	See Signature Algorithm

Response Fields

Field	Type	Description
id	string	Platform order ID
trans_id	string	Merchant order ID
order_amount	string	Order amount
payed_amount	string	Actual paid amount
ratio	number	Merchant fee ratio
currency	string	Currency
channel	string	Channel code. Note that the query response uses channel, not code
status	number	Order status
created_at	string	Creation time
payed_at	string | null	Payment time
callback_at	string | null	Callback completion time
canceled_at	string | null	Cancel time

Status Values

Status	Meaning
1	Order creation failed
10	Vendor error
20	Waiting for payment
30	Abnormal
40	Callback timeout
41	Callback abnormal
42	Amount mismatch
50	Canceled
60	Completed

Example

{
  "code": 200,
  "payload": {
    "id": "C202605040001",
    "trans_id": "ORDER-10001",
    "order_amount": "100.00",
    "payed_amount": "100.00",
    "ratio": 1.2,
    "currency": "VND",
    "channel": "bank",
    "status": 60,
    "created_at": "2026-05-04 10:05:00",
    "payed_at": "2026-05-04 10:06:10",
    "callback_at": "2026-05-04 10:06:12",
    "canceled_at": null
  }
}

The payment result is pushed by callback. See Collect Callback.