代收接口

创建代收订单

创建一笔新的代收订单。

• 请求方法：POST
• 接口路径：/api/v1/mch/pmt-orders
• POST 请求体必须是 JSON

对接说明

• currency 仅允许：PHP、THB、VND、USDT，大小写均可
• amount 校验范围：0 ~ 50000000000
• trans_id 必须全局唯一
• 若通道以 usdt 开头，系统会强制将 currency 改为 USDT
• 商户若开启代收限流，超限时会返回 429

请求参数

参数名	类型	必填	说明
mch_id	integer	是	商户号
trans_id	string	是	商户订单号，必须唯一，长度6-24位
currency	string	是	币种代码，参见系统货币代码
amount	string	是	订单金额。请使用字符串传递，例如 \"100.00\"
channel	string	是	通道代码，参见系统通道代码
callback_url	string	是	代收结果回调地址，必须为有效 URL
payer_account_no	string	否	付款账号。部分实名场景或上游通道会用到
payer_account_name	string	否	付款人姓名
payer_account_org	string	否	付款机构名称
mode	string	否	通道扩展参数，是否生效取决于具体通道
return_url	string	否	收银台完成后的回跳地址
uid	string	否	业务侧用户 ID，部分通道或风控场景会使用
remarks	string	否	商户备注，会作为订单附加信息保存
nonce	string	是	随机串, 长度：6-24
timestamp	integer	是	UNIX 时间戳
sign	string	是	参见签名算法

注意

部分扩展字段仅在特定业务场景下使用。若不确定是否需要，请先咨询平台对接人员。

返回字段

创建成功后，响应中通常会包含以下字段：

字段	类型	说明
id	string	平台订单号
trans_id	string	商户提供的订单号
order_amount	string	订单金额
ratio	number	商户费率
currency	string	币种
code	string	通道代码
status	number	初始通常为 20
created_at	string	创建时间
url	string	收银台地址
cashier_type	number	收银台类型
meta	object | null	附加收款信息，是否存在取决于通道

cashier_type 说明

值	说明
0	仅返回 url
1	仅返回 meta
9	同时返回 url 与 meta

返回示例

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

查询代收订单

• 请求方法：GET
• 接口路径：/api/v1/mch/pmt-orders

请求参数

参数名	类型	必填	说明
id	string	否	平台订单号；与 trans_id 二选一
trans_id	string	否	商户订单号；与 id 二选一
mch_id	integer	是	商户号
nonce	string	是	随机串，长度: 6-24
timestamp	integer	是	UNIX 时间戳
sign	string	是	参见签名算法

返回字段

字段	类型	说明
id	string	平台订单号
trans_id	string	商户订单号
order_amount	string	订单金额
payed_amount	string	实付金额
ratio	number	商户费率
currency	string	币种
channel	string	通道代码。注意这里的字段名是 channel，不是创建时的 code
status	number	订单状态
created_at	string	创建时间
payed_at	string | null	支付时间
callback_at	string | null	回调完成时间
canceled_at	string | null	取消时间

状态值

状态值	含义
1	下单失败
10	通道出错
20	待支付
30	掉单
40	回调超时
41	回调异常
42	金额不符
50	已取消
60	已完成

返回示例

{
  "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
  }
}

支付结果将通过回调推送，详见代收回调。