代付接口
创建代付订单
创建一笔新的代付订单。
- 请求方法：
POST - 接口路径：
/api/v1/mch/wdl-orders POST请求体必须是JSON
对接说明
amount必须大于0trans_id必须唯一channel必须是已启用的代付通道，否则会直接报错- 越南
account_no可以为字母数字组合，但不能是纯字母 - 查询接口返回的是面向商户对接的订单结果
请求参数
| 参数名 | 类型 | 越南 | 泰国 | 菲律宾 | 说明 |
|---|---|---|---|---|---|
mch_id | integer | ✅ | ✅ | ✅ | 商户号 |
trans_id | string | ✅ | ✅ | ✅ | 商户订单号，必须唯一，长度6-24位 |
channel | string | ✅ | ✅ | ✅ | 通道代码，参见系统通道代码 |
amount | string | ✅ | ✅ | ✅ | 订单金额，必须 > 0。请使用字符串传递，例如 "100.00" |
currency | string | ✅ | ✅ | ✅ | 币种代码，建议使用大写 |
account_no | string | ✅ | ✅ | ✅ | 收款账号，最长 34 位 |
account_name | string | ✅ | ✅ | ✅ | 收款姓名 |
account_org | string | ✅ | ✅ | ⭕️ | 收款机构名称 |
account_org_code | string | ✅ | ✅ | ⭕️ | 收款机构代码；越南、泰国必填 |
account_sub_org | string | ⭕️ | ⭕️ | ⭕️ | 分支行或补充机构信息 |
account_email | string | ⭕️ | ⭕️ | ⭕️ | 邮箱，若传入需满足邮箱格式 |
account_phone | string | ⭕️ | ⭕️ | ⭕️ | 手机号或联系电话 |
remarks | string | ⭕️ | ⭕️ | ⭕️ | 商户备注 |
callback_url | string | ✅ | ✅ | ✅ | 代付结果回调地址，必须为有效 URL |
nonce | string | ✅ | ✅ | ✅ | 随机串, 长度: 6-24 |
timestamp | integer | ✅ | ✅ | ✅ | UNIX 时间戳 |
sign | string | ✅ | ✅ | ✅ | 参见签名算法 |
说明
越南场景下，account_no 可以为字母数字组合，但不能是纯字母。
返回字段
创建成功后，响应中通常会返回以下字段：
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 平台订单号 |
trans_id | string | 商户提供的订单号 |
mch_id | integer | 商户号 |
channel | string | 通道代码 |
currency | string | 币种 |
order_amount | string | 订单金额 |
account_no | string | 收款账号 |
account_name | string | 收款姓名 |
account_org | string | 收款机构名称 |
callback_url | string | 回调地址 |
status | number | 订单请求已受理，固定返回 20 |
created_at | string | 创建时间 |
返回示例
json
{
"code": 200,
"payload": {
"id": "P202605040001",
"trans_id": "WDL-10001",
"mch_id": 10001,
"channel": "bank",
"currency": "VND",
"order_amount": "100.00",
"account_no": "2333667799212341",
"account_name": "NGUYEN XUAN HUNG",
"account_org": "PVCOMOBANK",
"callback_url": "https://merchant.example.com/callback/payout",
"status": 20,
"created_at": "2026-05-04 10:10:00"
}
}查询代付订单
- 请求方法：
GET - 接口路径：
/api/v1/mch/wdl-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 | 订单金额 |
pay_amount | string | null | 实际打款金额 |
ratio | number | 商户费率 |
currency | string | 币种 |
account_no | string | 收款账号 |
account_name | string | 收款姓名 |
account_org | string | 收款机构名称 |
account_sub_org | string | null | 分支行信息 |
status | number | 订单状态 |
created_at | string | 创建时间 |
payed_at | string | null | 完成时间 |
callback_at | string | null | 回调完成时间 |
canceled_at | string | null | 取消时间 |
attachments | string[] | 附件地址列表 |
状态说明
查询接口按以下规则返回订单结果：
| 返回状态 | 含义 |
|---|---|
20 | 已受理 |
21 | 打款中 |
50 | 已取消 |
60 | 已成功 |
注意
如需最终结果，请以回调通知为准。
返回示例
json
{
"code": 200,
"payload": {
"id": "P202605040001",
"trans_id": "WDL-10001",
"order_amount": "100.00",
"pay_amount": "100.00",
"ratio": 1.5,
"currency": "VND",
"account_no": "2333667799212341",
"account_name": "NGUYEN XUAN HUNG",
"account_org": "PVCOMOBANK",
"account_sub_org": null,
"status": 60,
"created_at": "2026-05-04 10:10:00",
"payed_at": "2026-05-04 10:15:00",
"callback_at": "2026-05-04 10:15:03",
"canceled_at": null,
"attachments": []
}
}最终结果会通过回调推送，详见代付回调。