代付接口（Payout）

接口概览

代付接口用于商户向用户发起付款（打款到银行卡/电子钱包）。

接口	方法	路径	说明
代付下单	POST	/api/peerPay/order	创建代付订单
订单查询	POST	/api/peerPay/query	根据商户订单号查询代付状态
回调通知	POST	商户配置的 notifyUrl	代付结果主动通知商户

请求格式

• Content-Type: application/json
• 请求方式: POST
• 请求体: JSON 格式

签名机制

与代收接口完全一致，支持两种签名方式，通过请求参数 signType 指定，默认 RSA。

重要

• sign 和 signType 两个字段本身 不参与签名计算
• 不传 signType 时默认使用 RSA
• 响应签名方式与请求一致

RSA 签名（默认）

1. 提取除 sign、signType 外的所有非空参数
2. 按参数名 ASCII 字典序 排序
3. 拼接成 key1=value1&key2=value2... 格式（不拼接 &key=secretKey）
4. 使用 RSA 私钥（SHA256WithRSA）签名
5. Base64 编码后作为 sign 字段值

MD5 签名

1. 提取除 sign、signType 外的所有非空参数
2. 按参数名 ASCII 字典序 排序
3. 拼接成 key1=value1&key2=value2... 格式
4. 末尾拼接 &key=secretKey
   • 其中 secretKey = MD5(alliesCode + ":" + alliesSecret)
5. MD5 加密后转大写

详细的 PHP/Java 签名代码请参考 代收接口签名示例。

接口流程

sequenceDiagram
    participant M as 商户
    participant API as API服务端
    participant CH as 代付通道

    M->>API: POST /api/peerPay/order
    Note over M,API: JSON + 签名（RSA默认/MD5）
    API->>API: 验签 + 参数校验 + 余额校验
    API->>API: 创建结算单（审核中）

    alt 自动代付
        API->>CH: 调用通道代付
        CH-->>API: 代付结果
    else 需要TG确认
        API->>M: 返回订单号（待确认）
        Note over API: 管理员TG确认后继续
    end

    API-->>M: 返回 outTradeNo + sign

    Note over CH: 代付处理完成

    CH->>API: 代付结果回调
    API->>M: POST notifyUrl（含 sign + rsaSign）
    M-->>API: 返回 SUCCESS

代付订单状态

状态值	说明
0	审核中
1	审核成功
2	审核失败
3	代付中
4	代付已转账（成功）
5	暂停代付

状态流转

flowchart LR
    A[审核中 0] -->|审核通过| B[审核成功 1]
    A -->|审核拒绝| C[审核失败 2]
    B -->|通道处理| D[代付中 3]
    D -->|转账完成| E[代付已转账 4]
    D -->|手动暂停| F[暂停代付 5]
    F -->|恢复| D

错误码

错误码	说明
10000	成功
1001	商户不存在 / 未开启代付
1003	通道限额不满足
1004	商户通道参数未配置
1008	IP不在白名单
1010	请求参数为空
1011	签名参数sign为空
1012	签名验证失败
2005	金额为空
2006	订单号为空
2007	回调地址为空
2008	订单号已存在
2012	订单号错误
2014	签名为空
2017	通道未授权
2018	银行卡号为空 / 附加数据为空
2019	银行账户名为空
2020	银行名称为空
3001	钱包余额不足
9999	系统错误