支付 API 文档

简体中文

English

简体中文

English

Appearance

代付API开发接口文档 ​

以下为代付平台的 API 接口文档详细说明，帮助商户快速接入代付下单、查单和余额查询服务。

1、目录 ​

1.1、代付下单

1.2、代付查单

1.3、代付余额查询

2、接口说明 ​

2.1 接口基础信息 ​

2.1.1 请求格式 ​

所有接口均使用 POST 方式请求，编码参数 UTF-8，请求体格式为 application/json。

2.1.2 通用请求参数 ​

参数类型是否必填说明备注
mchNostring是商户号由平台分配，建议使用商户 APIKey
reqTimeint64是请求时间戳13 位毫秒时间戳
signstring是请求签名见验签说明

2.1.3 响应格式 ​

所有接口响应格式统一如下：

参数类型说明
codeint32状态码，0 表示成功，其他表示失败
msgstring响应说明
signstring响应签名，部分失败场景可能为空
dataobject返回数据，具体结构见各接口说明

2.1.4 签名说明 ​

为了保证商户请求参数不被篡改，平台对开放接口提供 MD5 摘要签名认证。

完整签名规则、拼接示例和各语言代码示例请见签名算法。

注意事项：

  1. sign 本身不参与签名。
  2. 参数名大小写必须与接口字段一致。
  3. 金额按平台约定的整数单位传输，不传小数。
  4. reqTime 使用 13 位毫秒时间戳。

2.1.5 金额说明 ​

代付接口金额字段使用整数传输，单位为 0.0001 元，即真实金额乘以 10000 后传输。

示例：

真实金额接口 amount
0.5 元5000
1 元10000
100 元1000000

3、接口明细 ​

3.1 代付下单 ​

3.1.1 场景说明 ​

商户提交代付订单，平台受理后返回平台代付订单号和订单状态。商户订单号必须唯一，重复提交会返回订单已存在。

3.1.2 接口详情 ​

接口地址

项目内容
URL/api/v1/payout/order
请求方式POST
Content-Typeapplication/json
编码参数UTF-8

请求参数示例

json
{
  "mchNo": "10001",
  "mchOrderNo": "PO202406010001",
  "amount": 1000000,
  "accountName": "张三",
  "accountNo": "6222020202020202020",
  "bankName": "ICBC",
  "bankBranch": "Shanghai Branch",
  "notifyUrl": "https://merchant.example.com/notify/payout",
  "payCode": "BANK",
  "remark": "代付测试订单",
  "reqTime": 1717651200000,
  "sign": "MD5_UPPER_SIGN"
}

字段说明

字段名称类型是否必填说明
mchNostring是商户号
mchOrderNostring是商户代付订单号，商户侧必须唯一
amountint64是代付金额，单位：0.0001 元
accountNamestring是收款人姓名
accountNostring是收款账号/银行卡号
bankNamestring是收款银行或机构名称
bankBranchstring是支行或机构附注
notifyUrlstring是异步通知地址；如不需要通知，请固定传 NOURL，不建议传空字符串
payCodestring是代付通道编码
remarkstring否商户备注，原样透传或用于对账
reqTimeint64是13 位毫秒时间戳
signstring是MD5 大写签名

3.1.3 返回状态码 ​

code说明
0受理成功
200026签名验证失败
其他业务失败，具体以响应 msg 为准

3.1.4 响应示例 ​

成功响应示例

json
{
  "code": 0,
  "msg": "success",
  "sign": "MD5_UPPER_SIGN",
  "data": {
    "payoutOrderId": "PO20240601000001",
    "mchOrderNo": "PO202406010001",
    "amount": 1000000,
    "state": 1,
    "createdAt": 1717651200000
  }
}

失败响应示例

json
{
  "code": 200026,
  "msg": "签名验证失败"
}

data字段说明

字段名称类型说明
payoutOrderIdstring平台代付订单号
mchOrderNostring商户代付订单号
amountint64代付金额，单位：0.0001 元
stateint32订单状态，见订单状态说明
createdAtint64创建时间，13 位毫秒时间戳

3.2 代付查单 ​

3.2.1 场景说明 ​

商户可通过商户代付订单号或平台代付订单号查询订单状态。

3.2.2 接口详情 ​

接口地址

项目内容
URL/api/v1/payout/query
请求方式POST
Content-Typeapplication/json
编码参数UTF-8

请求参数示例

json
{
  "mchNo": "10001",
  "mchOrderNo": "PO202406010001",
  "payoutOrderId": "PO20240601000001",
  "reqTime": 1717651200000,
  "sign": "MD5_UPPER_SIGN"
}

请求字段说明

字段名称类型是否必填说明
mchNostring是商户号
mchOrderNostring否商户代付订单号，与 payoutOrderId 二选一
payoutOrderIdstring否平台代付订单号，与 mchOrderNo 二选一
reqTimeint64是13 位毫秒时间戳
signstring是MD5 大写签名

3.2.3 返回状态码 ​

code说明
0查询成功
200026签名验证失败
其他业务失败，具体以响应 msg 为准

3.2.4 响应示例 ​

成功响应示例

json
{
  "code": 0,
  "msg": "success",
  "sign": "MD5_UPPER_SIGN",
  "data": {
    "payoutOrderId": "PO20240601000001",
    "mchOrderNo": "PO202406010001",
    "amount": 1000000,
    "state": 3,
    "successTime": 1717651800000,
    "remark": ""
  }
}

失败响应示例

json
{
  "code": 404,
  "msg": "订单不存在"
}

data字段说明

字段名称类型说明
payoutOrderIdstring平台代付订单号
mchOrderNostring商户代付订单号
amountint64代付金额，单位：0.0001 元
stateint32订单状态，见订单状态说明
successTimeint64成功时间，13 位毫秒时间戳
remarkstring失败原因或备注

3.3 代付余额查询 ​

3.3.1 场景说明 ​

商户查询当前账户可用余额和冻结余额。

3.3.2 接口详情 ​

接口地址

项目内容
URL/api/v1/payout/balance
请求方式POST
Content-Typeapplication/json
编码参数UTF-8

请求参数示例

json
{
  "mchNo": "10001",
  "reqTime": 1717651200000,
  "sign": "MD5_UPPER_SIGN"
}

请求字段说明

字段名称类型是否必填说明
mchNostring是商户号
reqTimeint64是13 位毫秒时间戳
signstring是MD5 大写签名

3.3.3 返回状态码 ​

code说明
0查询成功
200026签名验证失败
其他业务失败，具体以响应 msg 为准

3.3.4 响应示例 ​

成功响应示例

json
{
  "code": 0,
  "msg": "success",
  "sign": "MD5_UPPER_SIGN",
  "data": {
    "mchNo": "10001",
    "mchName": "测试商户",
    "balance": 10000000,
    "frozenBalance": 500000
  }
}

data字段说明

字段名称类型说明
mchNostring商户号
mchNamestring商户名称
balanceint64可用余额，单位：0.0001 元
frozenBalanceint64冻结余额，单位：0.0001 元

4、异步通知说明 ​

4.1 通知场景 ​

代付订单状态发生最终变化时，平台会按照商户下单时传入的 notifyUrl 推送异步通知。若下单时 notifyUrl 传 NOURL，平台不会向该订单推送异步通知。

异步通知用于商户系统接收代付结果，商户收到通知后应根据平台订单号或商户订单号更新本地订单状态，并做好幂等处理。

4.2 请求方式 ​

项目内容
请求方式POST
Content-Typeapplication/json
编码参数UTF-8
通知地址商户下单传入的 notifyUrl

4.3 通知参数 ​

平台通知商户时，请求体为 JSON 格式，字段如下：

字段名类型是否必返说明
platform_order_nostring是平台代付订单号
merchant_order_nostring是商户代付订单号
merchant_idint64是平台商户 ID
amountint64是订单金额，单位：0.0001 元
actual_amountint64是实际出款金额，单位：0.0001 元
success_amountint64是成功金额，单位：0.0001 元
statusint32是订单状态，见 订单状态说明
fail_reasonstring是失败原因；成功时通常为空
currencystring是币种，例如 RMB

商户处理通知成功后，请返回 HTTP 2xx 状态码，并在响应体中返回 SUCCESS 字符串。

4.4 响应示例 ​

响应参数示例

json
{
  "platform_order_no": "PO20240601000001",
  "merchant_order_no": "MCH202406010001",
  "merchant_id": 10001,
  "amount": 1000000,
  "actual_amount": 1000000,
  "success_amount": 1000000,
  "status": 3,
  "fail_reason": "",
  "currency": "RMB"
}

4.5 商户响应要求 ​

商户回调接口收到通知并处理成功后，应返回 HTTP 2xx 状态码，且响应体内容为 SUCCESS。平台同时满足这两个条件时，认为通知成功。

商户响应平台处理
HTTP 2xx 且响应体为 SUCCESS认为通知成功
非 HTTP 2xx，或响应体不是 SUCCESS认为通知失败，并记录商户响应内容
请求超时或网络异常认为通知失败，并记录错误信息

商户响应示例：

text
SUCCESS

4.6 幂等处理建议 ​

商户应以 platform_order_no 或 merchant_order_no 作为唯一标识处理回调通知。同一订单可能因网络异常、人工补发或平台重试产生多次通知，商户系统应保证重复通知不会重复入账或重复更新关键业务数据。

建议处理流程：

  1. 根据 platform_order_no 或 merchant_order_no 查询本地订单。
  2. 校验订单金额、商户号、币种等核心信息是否一致。
  3. 若订单已处理为最终状态，直接返回成功。
  4. 若订单未处理，则根据 status 更新本地状态。
  5. 记录完整通知请求体和处理结果，便于后续排查。

4.7 注意事项 ​

  1. 平台通知请求体不额外携带 sign 字段，请以 HTTPS、IP 白名单和订单信息校验保障安全。
  2. amount、actual_amount、success_amount 均为整数金额，单位为 0.0001 元。
  3. upstream_code 和 upstream_msg 为可选字段，只有存在上游返回信息时才会返回。
  4. 商户回调接口应尽快响应，避免因处理耗时超过 10 秒导致平台判定通知失败。

5、状态码说明 ​

5.1 通用状态码 ​

code说明
0成功
200026签名验证失败
其他业务失败，具体以响应 msg 为准

5.2 订单状态说明 ​

state说明
0待处理
1处理中
2预留状态，商户侧无需作为最终状态处理
3成功
4失败
5驳回
6已冲正
7订单处理中

其中 3、4、5、6 为最终状态。商户收到最终状态后应做好幂等处理，避免重复入账或重复更新订单。

6、接入流程 ​

6.1 申请商户账号 ​

  1. 联系平台申请商户账号。
  2. 获取商户号和商户密钥。
  3. 配置请求 IP 白名单和回调地址。

6.2 开发对接 ​

  1. 根据本文档实现签名生成。
  2. 对接代付下单、查单和余额查询接口。
  3. 实现异步通知接收接口。
  4. 对订单号、回调通知做好幂等处理，并在通知处理成功后返回 SUCCESS。

6.3 测试联调 ​

  1. 使用测试商户号和密钥发起请求。
  2. 确认金额单位、签名、时间戳格式正确。
  3. 验证下单、查单、余额查询和异步通知流程。

6.4 上线准备 ​

  1. 切换生产商户号和密钥。
  2. 配置生产回调地址。
  3. 检查服务器 IP 白名单。
  4. 保留请求日志和回调日志，便于问题排查。

7、常见问题 ​

7.1 签名验证失败怎么办？ ​

  1. 确认 sign 字段没有参与签名。
  2. 确认字段按 ASCII 升序拼接。
  3. 确认空值字段没有参与签名。
  4. 确认末尾追加的是正确商户密钥。
  5. 确认最终 MD5 结果转换为 32 位大写。

7.2 金额为什么不能传小数？ ​

接口金额使用整数单位传输，单位为 0.0001 元。例如真实金额 1 元 应传 10000。

7.3 订单号重复怎么办？ ​

mchOrderNo 是商户侧唯一订单号。重复提交同一个订单号会被平台识别为重复订单，建议商户侧保证订单号全局唯一。

7.4 查单应该使用哪个订单号？ ​

优先使用平台返回的 payoutOrderId 查询；如果商户侧未保存平台订单号，也可以使用 mchOrderNo 查询。

7.5 回调接收不到怎么办？ ​

  1. 检查 notifyUrl 是否可公网访问。
  2. 检查回调接口是否可在 10 秒内返回 HTTP 2xx 和 SUCCESS。
  3. 检查回调接口是否超时或返回异常。
  4. 查看平台订单日志和商户服务日志。

8、联系方式 ​

如有任何问题，请联系平台技术支持。

文档版本： v1.0

最后更新： 2026-06-25

支付 API 文档

Copyright © 2026