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	(Optional, Used by real-name payment)Payer account
payer_account_name	string	No	(Optional, Used by real-name payment)Payer name
payer_account_org	string	No	(Optional, Used by real-name payment)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

Response 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,..."
    }
  }
}

THB Custom Cashier: Upload Payment Proof

When a THB create-order response includes receiving details and qr_code in meta, you may render your own cashier. After payment, upload and bind the payment proof in this order so the platform can perform ESLIP verification.

Permissions and Restrictions

• Both endpoints only support THB collect orders that belong to the authenticated merchant.
• The API key must have the collect.proof.upload (collect proof upload) capability.
• Both POST requests use a JSON body and must include the common signing parameters.
• Bind the proof with the returned key; do not construct a storage key yourself.

1. Get a Presigned Upload URL

• Method: POST
• Path: /api/v1/mch/pmt-orders/proof-upload-url

Request Parameters

Parameter	Type	Required	Description
id	string	One of	Platform order ID
trans_id	string	One of	Merchant order ID
key	string	Yes	Proof filename or custom object suffix, maximum 180 characters

Response Fields

Field	Type	Description
key	string	Object key to use when binding the uploaded proof
upload_url	string	Presigned PUT upload URL, valid for 10 minutes
headers	object	Headers that must be included in the upload request
ref_url	string	Proof URL after upload

Response Example

{
  "code": 200,
  "payload": {
    "key": "cashier/th/C202605040001/slip.jpg",
    "upload_url": "https://storage.example.com/...",
    "headers": {
      "Content-Type": "image/jpeg"
    },
    "ref_url": "https://cdn.example.com/cashier/th/C202605040001/slip.jpg"
  }
}

Upload the image binary to upload_url with a PUT request, including the returned headers unchanged. Then call the binding endpoint.

2. Bind a Proof to a Collect Order

• Method: POST
• Path: /api/v1/mch/pmt-orders/proof

Request Parameters

Parameter	Type	Required	Description
id	string	One of	Platform order ID
trans_id	string	One of	Merchant order ID
uploaded_image_key	string	Yes	The key returned by the previous endpoint

Binding another proof to the same order replaces the previous proof and triggers ESLIP parsing again.

Response Example

{
  "code": 200,
  "payload": {
    "id": "C202605040001",
    "trans_id": "ORDER-10001"
  }
}

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

Value	Meaning
50	Canceled
60	Completed
other	Processing

Response 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.