创建代付
POST /api/v1/payout/create
创建及确认新单时会排除维护通道;已有正式订单仍使用原通道继续处理,不重复冻结资金。未生成正式订单的会话可改选其他合格的 active 通道,详见 通道维护说明。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
merchant_order_no |
string | 是 | 商户唯一代付订单号,最长 128 字符 |
amount |
string | 是 | 十进制代付金额 |
currency |
string | 是 | 大写币种代码 |
bank_code |
string | 否 | 平台银行或电子钱包代码,最长 64 字符;与 currency 组成身份。未传时由用户选择已映射选项 |
account_no |
string | 否 | 可选预填收款账号,最长 128 字符;未传时由用户填写 |
account_name |
string | 否 | 可选预填收款人姓名,最长 128 字符;未传时由用户填写 |
recipient_email |
string | 否 | 可选预填合法邮箱,最长 254 字符;未传时仅要求邮箱的通道显示补填 |
channel_code |
string | 否 | 可省略;传入时将收银台可选范围限定为该通道,仍须满足当前商户、币种、支付类型和限额要求 |
notify_url |
string | 否 | 异步通知地址;省略时使用商户默认通知地址,生产环境必须使用 HTTPS |
return_url |
string | 否 | 代付收银台手动返回地址,须为绝对 HTTP(S) URL,最长 2048 字节;未传或为空时无返回地址,不使用商户默认地址 |
收款资料规则:
| 阶段 | 规则 |
|---|---|
| 创建会话 | bank_code、account_no、account_name、recipient_email 支持部分提交或全部省略;amount、currency 必填。已提供资料须通过格式校验,并参与签名和创建幂等指纹;收银台显示完整账号、户名,用户不能修改。 |
| 收银台确认 | 选择通道后只显示尚未提供且该通道要求的字段。银行代码、账号和姓名须在确认前完整;recipient_email 仅在通道要求时补填。确认后才创建正式订单,并锁定通道和收款资料;重复提交沿用原选择。 |
通道匹配与余额预检通过后,全部省略收款资料时仍返回 payment_url。创建响应不返回银行列表;用户在收银台选择付款方式和已验证银行后填写资料。创建会话成功不代表代付到账。
返回链接前,平台会按匹配通道检查 可用余额 >= amount + 商户手续费;余额刚好足够时允许,无余额记录按不足处理。指定 channel_code 时只检查该通道,不能使用其他通道的较低手续费。银行匹配可能读取通道银行 API,查询失败不会生成会话。创建成功不冻结资金;用户确认时和正式建单时仍会重新校验。未生成正式订单的创建重试重新预检,已有正式订单继续返回原订单,不重复冻结。
省略收款资料的请求示例:
{
"api_key": "<PAYOUT_API_KEY>",
"merchant_id": "merchant_1001",
"merchant_order_no": "OUT202609160001",
"amount": "50.00",
"currency": "MYR",
"return_url": "https://merchant.example.com/payout/result",
"timestamp": "1789516800",
"nonce": "fc687af8-5915-4db0-95ee-c21b09ec3553",
"sign": "<64位小写HMAC-SHA256>"
}
响应示例:
{
"code": 0,
"message": "OK",
"data": {
"checkout_mode": "cashier",
"platform_order_no": "W202609160001",
"merchant_order_no": "OUT202609160001",
"amount": "50.00",
"currency": "MYR",
"status": "awaiting_payment_method",
"payment_url": "https://cashier.example.com/#/cashier/<opaque-token>",
"expired_at": "2026-09-16T15:30:00Z"
},
"request_id": "req_01JEXAMPLE"
}
未选通道且未提交时,会话按 expired_at 到期;选定通道进入提交流程后,以正式订单状态为准。