中国代付（Payout）

商户 API 前缀：/api/v1/merchant。鉴权 Header 见 签名规范。

创建代付订单

创建中国代付订单并发布至平台任务市场。成功后将冻结商户钱包 netAmount（amount + fee）。

接口

项目	值
Method	POST
Path	/api/v1/merchant/payout/create

请求体

字段	类型	必填	说明
merchantOrderNo	string	是	商户订单号，唯一
countryCode	string	是	CN
currency	string	是	CNY
amount	string/number	是	代付金额（元，给收款人）
receiverName	string	是	收款人姓名（与银行卡开户名一致）
receiverAccount	string	是	银行卡号
receiverBankName	string	是	开户银行名称，如 中国工商银行
receiverBankCode	string	建议	联行号 / 银行编码
receiverPhone	string	否	预留手机号
notifyUrl	string	否	本单回调；为空则用商户默认 callbackUrl
metadata	object	否	扩展，如 { "branch": "上海浦东支行" }

出款方式 payoutMethod（响应字段）

填写银行信息后固定为 BANK_TRANSFER。

响应 data 字段

字段	说明
orderNo	平台订单号（PO 前缀）
payoutTaskId	关联的平台代付任务 ID
status	成功创建后为 market_available
netAmount	实际冻结金额（含手续费）

cURL 示例

API_BASE="https://api.soranopro.com"
BODY='{"merchantOrderNo":"CNPAYOUT20260608001","countryCode":"CN","currency":"CNY","amount":"10000.00","receiverName":"张三","receiverAccount":"6222021234567890123","receiverBankName":"中国工商银行","receiverBankCode":"102100099996","receiverPhone":"13800138000","notifyUrl":"https://merchant.soranopro.com/cn/payout/cb"}'

curl -X POST "${API_BASE}/api/v1/merchant/payout/create" \
  -H "Content-Type: application/json" \
  -H "X-Merchant-No: M42" \
  -H "X-Timestamp: 1718198400" \
  -H "X-Nonce: $(uuidgen)" \
  -H "X-Sign: ${SIGN}" \
  -d "${BODY}"

响应示例

{
  "code": 0,
  "msg": "ok",
  "data": {
    "orderNo": "PO20260608150000777777",
    "merchantOrderNo": "CNPAYOUT20260608001",
    "countryCode": "CN",
    "currency": "CNY",
    "amount": "10000.00",
    "feeAmount": "30.00",
    "netAmount": "10030.00",
    "status": "market_available",
    "payoutMethod": "BANK_TRANSFER",
    "payoutTaskId": 305,
    "createdAt": "2026-06-08T15:00:00Z"
  }
}

失败场景

msg（示例）	原因
merchant balance insufficient	钱包可用余额不足
merchant order no already exists	merchantOrderNo 重复

查询代付订单

接口

项目	值
Method	GET
Path	/api/v1/merchant/payout/query

Query 参数（二选一）

参数	说明
orderNo	平台订单号
merchantOrderNo	商户订单号

异步回调

收到回调后的验签、幂等处理、应答 OK 与重试策略，见 异步回调接入指南。

代付订单 完成（status=completed）后，平台 POST 至 notifyUrl 或商户默认 callbackUrl。

Body 示例

{
  "orderType": "payout",
  "orderNo": "PO20260608150000777777",
  "merchantOrderNo": "CNPAYOUT20260608001",
  "status": "completed",
  "amount": "10000.00",
  "feeAmount": "30.00",
  "netAmount": "10030.00",
  "currency": "CNY",
  "countryCode": "CN",
  "completedAt": 1718205600
}

Header 签名机制与代收回调相同，使用 平台公钥 验签。

商户响应

HTTP 200 + Body OK

注意事项

1. 任务 取消/过期 时订单可能为 cancelled，不会 发送完成回调，冻结资金会退回
2. 重复通知请幂等处理
3. 户名与卡号不匹配可能导致任务失败，请与运营确认校验规则
4. 代付进行中状态可通过查询接口轮询：market_available → processing → completed

订单状态

status	说明
created	创建中（瞬时）
market_available	已上架任务市场
processing	平台用户已接单
completed	代付完成，已扣款并回调
failed	创建或执行失败
cancelled	已取消，冻结款退回