文档目录 · 创建代付

创建代付

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 到期;选定通道进入提交流程后,以正式订单状态为准。

搜索文档