Collection API

Collection Order Placement

Call this API to initiate a payment request. On success, it will return order information.

• Request Method: POST
• API Path: http://[API Domain]/api/v1/mch/pmt-orders
• Request Parameters:

Name	Type	Required	Description
mch_id	number	✅	Merchant ID, please check in the merchant backend configuration
trans_id	string	✅	Merchant transaction ID, provided by the merchant
currency	string	✅	Currency code, see System Currency Codes
amount	string	✅	Order amount, in standard fiat units. RMB keeps two decimals. VND is an integer. Use string, like "100.00"
channel	string	✅	Channel code, use mock for integration testing. For other country codes, see System Channel Codes
bank_code	string	⭕️	Required for specific channels, will be specified during integration
payer_account_no	string	⭕️	Payer account number (used in real-name scenarios)
payer_account_name	string	⭕️	Payer account name (used in real-name scenarios)
payer_acccount_org	string	⭕️	Payer account bank (used in real-name scenarios)
callback_url	string	✅	The platform will notify the payment result via HTTP POST after successful payment
mode	string	⭕️	'auto' or 'manual'. Use 'auto' to pay directly or 'manual' to select bank manually. Default is 'auto'
return_url	string	⭕️	The platform will jump to this url after successful payment
uid	string	⭕️	User ID. You can use your system's user ID or its MD5 value. For USDT channel, this is required
remarks	string	⭕️	Order remarks, will be returned as-is in the callback
nonce	string	✅	Random string, at least 6 characters
timestamp	number	✅	UNIX timestamp, 10 digits
sign	string	✅	Parameter signature. See Signature Algorithm

• Response

Name	Type	Description
id	string	Platform unique order ID
mch_id	number	Merchant ID
trans_id	string	Transaction ID
order_amount	number	Order amount
channel	string	Payment channel code
status	number	Order status, newly created order is 20
url	string	Order URL (H5 page, can be shown directly to the end user)
cashier_type	number	Cashier type, see "cashier_type Description"
meta	object	(Vietnam bank channel only) Original receiving account info, see below
meta.account_no	string	(Vietnam bank channel only) Receiving account number
meta.account_name	string	(Vietnam bank channel only) Receiving account name
meta.account_org	string	(Vietnam bank channel only) Receiving institution name
meta.account_org_code	string	(Vietnam bank channel only) Receiving institution code
meta.qr_url	string	(Vietnam bank channel only) Vietnam bank QR code

• About cashier_type

0: Only cashier page link is returned, see the url field above
1: Only receiving account info is returned, see the meta field above
9: Both url and meta fields are returned. By default, you can use the url to get the cashier page link. If you want to use a custom cashier, you can use the receiving account info in the meta field

Response Example

{
  "code": 200,
  "payload": {
    "id": "ET1729187424AJCT",
    "mch_id": "8888",
    "trans_id": "Order number/transaction ID submitted by merchant",
    "channel": "bank",
    "order_amount": 101,
    "status": 20,
    "cashier_type": 9,
    "url": "http://cashier.money.com/cashier/order?id=abcdefg123",
    "meta": {
      "account_no": "898123767665",
      "account_name": "THAN NHA TRONG",
      "account_org": "CIMB",
      "account_org_code": "422589"
    },
    "sign": "e0c0a5a0c5ddeb3f3887e273df49568b"
  }
}

After successful collection, the system will send a notification to the platform. See Collection Callback for details.

Collection Order Query

• Request Method: GET
• API Path: http://[API Domain]/api/v1/mch/pmt-orders
• Request Example: http://[API Domain]/api/v1/mch/pmt-orders?id=[OrderID]&mch_id=[MerchantID]&sign=[Signature]
• Request Parameters:

Name	Type	Required	Description
id	string	✅	Order ID or transaction ID. Note: this parameter must be included in the signature
mch_id	number	✅	Merchant ID, please check in the merchant backend configuration
nonce	string	✅	Random string, at least 6 characters
timestamp	number	✅	UNIX timestamp, 10 digits
sign	string	✅	Parameter signature. See Signature Algorithm

• Response:

Name	Type	Description
id	string	Platform unique order ID
mch_id	number	Merchant ID
trans_id	string	Transaction ID
order_amount	number	Order amount
payed_amount	number	Actual paid amount. If it does not match the order amount, please confirm whether to credit
channel	string	Payment channel code
status	number	Status, 60 means payment successful, others mean not paid
created_at	string	Creation time

Response Example

{
  "code": 200,
  "payload": {
    "id": "EOu154sgKfZB",
    "mch_id": "8888",
    "trans_id": "Merchant's transaction ID",
    "amount": 100,
    "channel": "bank",
    "status": 20,
    "url": "http://cashier.money.com/cashier/order?id=abcdefg123",
    "sign": "e0c0a5a0c5ddeb3f3887e273df49568b",
    "created_at": "2020-09-09 12:21:44"
  }
}