代收接口文档

本文档只说明代收商户开放接口。所有平台接口均使用 POST 请求，请求体为 application/json，字符编码为 UTF-8。

1. 接口基础信息

项目	内容
请求方式	POST
Content-Type	application/json
字符编码	UTF-8

如果请求使用 application/x-www-form-urlencoded、multipart/form-data 或其它格式，平台会按参数校验失败处理。

2. 通用参数

2.1 通用请求参数

字段	类型	是否必填	说明
`mchNo`	string	是	商户号，由平台分配
`reqTime`	int64	是	13 位毫秒时间戳，请求时间允许前后 5 分钟误差
`sign`	string	是	MD5 大写签名，见签名算法

2.2 通用响应结构

字段	类型	说明
`code`	int32	响应码，只有 `0` 表示接口成功，其它均表示失败
`msg`	string	响应说明，成功时为 `SUCCESS`
`sign`	string	响应签名；仅成功响应返回
`data`	object	业务数据；失败响应不返回

平台以 code 判断接口是否调用成功：只有 code=0 表示成功，其它 code 均表示接口失败。对于代收下单接口，code 非 0 时表示订单创建失败，商户不得按该响应继续展示支付页面链接或更新为成功订单。

成功响应示例：

json

{
  "code": 0,
  "msg": "SUCCESS",
  "sign": "MD5_UPPER_SIGN",
  "data": {}
}

失败响应示例：

json

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

3. 代收下单

商户创建代收订单。平台受理成功后返回平台代收订单号、订单状态和支付页面链接。

重要提示：发起代收下单时，可能因产品配置的匹配浮动范围影响，出现未匹配到当前下单金额支付页面链接的情况。平台可能提供其它金额的支付页面链接供用户付款，因此最终付款金额、查单结果或异步通知金额可能与商户下单金额不一致，商户给用户展示的付款金额及后续入账金额请以平台返回的 payableAmount 和异步通知金额为准！

3.1 接口地址

项目	内容
URL	`/api/v1/collection/order`
请求方式	POST
Content-Type	application/json

3.2 请求参数

字段	类型	是否必填	说明
`mchNo`	string	是	商户号
`mchOrderNo`	string	是	商户代收订单号，建议商户侧全局唯一
`userId`	string	是	商户侧用户 ID，字符串，例如 `user-001`；参与请求签名
`channelCode`	string	是	代收产品编码，商户后台-API管理-代收通道页面查询获取
`amount`	string	是	期望金额，金额字符串，例如 `100.00`
`clientIp`	string	是	终端用户 IPv4 地址
`notifyUrl`	string	是	异步通知地址，必须是公网可访问的 `http` 或 `https` 地址
`returnUrl`	string	否	商户跳转地址预留字段；如传入，会参与请求签名
`extParam`	string	否	商户扩展参数，查单时原样返回
`reqTime`	int64	是	13 位毫秒时间戳
`sign`	string	是	MD5 大写签名

3.3 请求示例

json

{
  "mchNo": "10001",
  "mchOrderNo": "COL202609110001",
  "userId": "user-001",
  "channelCode": "BANK_CARD",
  "amount": "100.00",
  "clientIp": "203.0.113.10",
  "notifyUrl": "https://merchant.example.com/notify/collection",
  "returnUrl": "https://merchant.example.com/payment/result",
  "extParam": "vip10001",
  "reqTime": 1789051200000,
  "sign": "5493647C63D2C9950566ED7E40538F64"
}

3.4 成功响应

json

{
  "code": 0,
  "msg": "SUCCESS",
  "sign": "MD5_UPPER_SIGN",
  "data": {
    "payOrderId": "CO20260911000001",
    "mchOrderNo": "COL202609110001",
    "amount": "100.00",
    "payableAmount": "99.40",
    "adjustmentAmount": "-0.60",
    "payDataType": "payUrl",
    "payData": "https://pay.example.com/collection/pay?mchOrderNo=COL202609110001",
    "orderState": 3,
    "createdAt": 1789051200000
  }
}

3.5 `data` 字段

字段	类型	说明
`payOrderId`	string	平台代收订单号；正式单返回
`mchOrderNo`	string	商户代收订单号
`amount`	string	期望金额，金额字符串，例如 `100.00`
`payableAmount`	string	实际应付金额，金额字符串，例如 `99.40`
`adjustmentAmount`	string	实际应付金额与期望金额的差额，金额字符串，例如 `-0.60`
`payDataType`	string	支付页面链接类型，当前为 `payUrl`
`payData`	string	支付页面链接；商户将该链接展示或跳转给付款用户
`orderState`	int32	订单状态，见下方订单状态说明
`createdAt`	int64	创建时间，13 位毫秒时间戳

payData 是字符串字段。商户需要先按普通字符串验签；当 payDataType=payUrl 时，payData 即为完整支付页面链接，请原样展示或跳转，不要重新拼接、截断或转义后再使用。

3.6 未获得支付页面链接的响应

代收下单未获得支付页面链接时，也可能返回成功响应，业务状态为失败终态：

json

{
  "code": 0,
  "msg": "SUCCESS",
  "sign": "MD5_UPPER_SIGN",
  "data": {
    "payOrderId": "CO20260911000003",
    "mchOrderNo": "COL202609110003",
    "amount": "100.00",
    "payDataType": "",
    "payData": "",
    "orderState": 7,
    "createdAt": 1789051200000
  }
}

商户应根据 orderState 判断订单结果；orderState=7 表示本次订单已失败。

3.7 订单状态

订单状态只在接口 code=0 且返回 data 时有业务意义。

状态值	说明	是否终态
`1`	待匹配	否
`2`	匹配中	否
`3`	匹配成功待上传凭证	否
`4`	已上传凭证待审核	否
`5`	审核成功/出款中	否
`6`	已成功	是
`7`	已失败	是
`8`	已取消	是

商户应以查单接口返回的 state 或下单接口返回的 orderState 作为订单状态依据。终态订单需要幂等处理，避免重复入账或重复更新。

3.8 幂等规则

同一商户使用同一个 mchOrderNo 重复请求时：

场景	平台处理
请求核心字段与原订单一致	返回原订单结果
请求金额、通道编码、通知地址等核心字段发生变化	返回业务冲突错误
订单号已被其它商户占用	返回 `200088`

4. 代收查单

商户仅使用商户代收订单号 mchOrderNo 查询订单状态。payOrderId 仅作为平台返回的结果字段用于记录和对账，不作为查单请求参数。建议商户主动查单做结果补偿，不完全依赖异步通知。

4.1 接口地址

项目	内容
URL	`/api/v1/collection/query`
请求方式	POST
Content-Type	application/json

4.2 请求参数

字段	类型	是否必填	说明
`mchNo`	string	是	商户号
`mchOrderNo`	string	是	商户代收订单号
`reqTime`	int64	是	13 位毫秒时间戳
`sign`	string	是	MD5 大写签名

4.3 请求示例

json

{
  "mchNo": "10001",
  "mchOrderNo": "COL202609110001",
  "reqTime": 1789051260000,
  "sign": "MD5_UPPER_SIGN"
}

4.4 成功响应

json

{
  "code": 0,
  "msg": "SUCCESS",
  "sign": "MD5_UPPER_SIGN",
  "data": {
    "payOrderId": "CO20260911000001",
    "mchOrderNo": "COL202609110001",
    "amount": "100.00",
    "channelCode": "BANK_CARD",
    "state": 6,
    "clientIp": "203.0.113.10",
    "payableAmount": "99.40",
    "adjustmentAmount": "-0.60",
    "payDataType": "payUrl",
    "payData": "https://pay.example.com/collection/pay?mchOrderNo=COL202609110001",
    "actualReceivedAmount": "99.40",
    "fee": "0.99",
    "netAmount": "98.41",
    "createdAt": 1789051200000,
    "successTime": 1789051500000,
    "extParam": "vip10001"
  }
}

4.5 `data` 字段

字段	类型	说明
`payOrderId`	string	平台代收订单号
`mchOrderNo`	string	商户代收订单号
`amount`	string	期望金额，金额字符串，例如 `100.00`
`channelCode`	string	代收产品编码，商户后台-API管理-代收通道页面查询获取
`state`	int32	订单状态，见代收下单的订单状态说明
`clientIp`	string	终端用户 IP
`payableAmount`	string	实际应付金额，金额字符串，例如 `99.40`
`adjustmentAmount`	string	实际应付金额与期望金额的差额，金额字符串，例如 `-0.60`
`payDataType`	string	支付页面链接类型，当前为 `payUrl`
`payData`	string	支付页面链接；商户将该链接展示或跳转给付款用户
`actualReceivedAmount`	string	实际到账金额，金额字符串，例如 `99.40`
`fee`	string	手续费，金额字符串，例如 `0.99`
`netAmount`	string	净额，金额字符串，例如 `98.41`
`createdAt`	int64	创建时间，13 位毫秒时间戳
`successTime`	int64	成功时间，13 位毫秒时间戳
`extParam`	string	商户扩展参数

5. 代收余额查询

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

5.1 接口地址

项目	内容
URL	`/api/v1/collection/balance`
请求方式	POST
Content-Type	application/json

5.2 请求参数

字段	类型	是否必填	说明
`mchNo`	string	是	商户号
`reqTime`	int64	是	13 位毫秒时间戳
`sign`	string	是	MD5 大写签名

5.3 请求示例

json

{
  "mchNo": "10001",
  "reqTime": 1789051500000,
  "sign": "MD5_UPPER_SIGN"
}

5.4 成功响应

json

{
  "code": 0,
  "msg": "SUCCESS",
  "sign": "MD5_UPPER_SIGN",
  "data": {
    "mchNo": "10001",
    "mchName": "测试商户",
    "balance": "100.00",
    "frozenBalance": "0.00"
  }
}

5.5 `data` 字段

字段	类型	说明
`mchNo`	string	商户号
`mchName`	string	商户名称
`balance`	string	可用余额
`frozenBalance`	string	冻结余额

余额查询成功时 code=0，商户应验签后读取 data；code 非 0 时表示请求失败，无需处理余额数据。

6. 异步通知

订单进入终态后，平台会向下单时提交的 notifyUrl 发送异步通知。商户收到通知后应验签、核对订单号和金额，并做好幂等处理。

重要提示：受产品配置的匹配浮动范围影响，异步通知中的金额可能与商户下单金额不一致。商户完成回调处理、入账或上分时，请以平台异步通知金额及订单最终状态为准！

6.1 通知请求

项目	内容
请求方式	POST
Content-Type	application/json
通知地址	下单时传入的 `notifyUrl`
超时时间	8 秒
尝试次数	最多 3 次

6.2 通知参数

字段	类型	是否必返	说明
`payOrderId`	string	是	平台代收订单号
`mchOrderNo`	string	是	商户代收订单号
`amount`	string	是	商户下单期望金额，金额字符串，例如 `100.00`
`state`	int32	是	订单状态，见代收下单的订单状态说明；成功为 `6`，失败为 `7`，取消为 `8`
`notifyType`	string	是	通知类型：`collection_success`、`collection_failed`、`collection_cancel`
`notifyState`	string	是	通知状态：`SUCCESS`、`FAILED`、`CANCELLED`
`payableAmount`	string	否	实际应付金额，金额字符串，例如 `99.40`
`adjustmentAmount`	string	否	实际应付金额与期望金额的差额，金额字符串，例如 `-0.60`
`actualReceivedAmount`	string	否	实际到账金额，金额字符串，例如 `99.40`；成功通知返回
`fee`	string	否	手续费，金额字符串，例如 `0.99`；成功通知返回
`netAmount`	string	否	净额，金额字符串，例如 `98.41`；成功通知返回
`successTime`	int64	否	成功时间，13 位毫秒时间戳；成功通知返回
`failTime`	int64	否	失败时间，13 位毫秒时间戳；失败通知返回
`cancelTime`	int64	否	取消时间，13 位毫秒时间戳；取消通知返回
`reason`	string	否	失败或取消原因
`extParam`	string	否	商户扩展参数，下单传入时原样返回
`sign`	string	是	通知签名

成功通知示例：

json

{
  "payOrderId": "CO20260911000001",
  "mchOrderNo": "COL202609110001",
  "amount": "100.00",
  "state": 6,
  "notifyType": "collection_success",
  "notifyState": "SUCCESS",
  "payableAmount": "99.40",
  "adjustmentAmount": "-0.60",
  "actualReceivedAmount": "99.40",
  "fee": "0.99",
  "netAmount": "98.41",
  "successTime": 1789051500000,
  "extParam": "vip10001",
  "sign": "MD5_UPPER_SIGN"
}

失败通知示例：

json

{
  "payOrderId": "CO20260911000002",
  "mchOrderNo": "COL202609110002",
  "amount": "100.00",
  "state": 7,
  "notifyType": "collection_failed",
  "notifyState": "FAILED",
  "failTime": 1789051500000,
  "reason": "未匹配到可用支付页面链接",
  "sign": "MD5_UPPER_SIGN"
}

取消通知示例：

json

{
  "payOrderId": "CO20260911000003",
  "mchOrderNo": "COL202609110003",
  "amount": "100.00",
  "state": 8,
  "notifyType": "collection_cancel",
  "notifyState": "CANCELLED",
  "cancelTime": 1789051500000,
  "reason": "商户主动取消代收订单",
  "sign": "MD5_UPPER_SIGN"
}

6.3 商户响应要求

推荐商户直接返回纯文本：

text

SUCCESS

平台也可识别 JSON 响应体中精确等于 SUCCESS 的字段值，例如：

json

{
  "code": 0,
  "msg": "SUCCESS"
}

以下响应会被视为失败：非 2xx HTTP 状态码、空响应、success 小写、SUCCESS OK、只包含 successful 等非精确值。

6.4 幂等处理建议

商户建议按以下顺序处理通知：

校验 sign。
使用 mchOrderNo 查询本地订单；payOrderId 可作为平台单号保存用于对账。
核对订单号、订单状态和金额字段。成功通知入账或上分时，以 actualReceivedAmount、fee、netAmount 等平台通知金额为准。
如果本地订单已经是终态，直接返回 SUCCESS。
如果本地订单未处理，则更新状态并记录通知日志。
处理成功后返回 HTTP 2xx 和 SUCCESS。

7. 接入流程

联系平台开通代收商户，获取 mchNo、商户密钥，并在商户后台-API管理-代收通道页面查询获取 channelCode。
配置请求 IP 白名单，确保调用平台接口的出口 IP 在白名单内。
按签名算法生成请求签名。
调用代收下单接口创建代收订单，向用户展示 payData 返回的支付页面链接。
使用查单接口和异步通知共同确认订单最终状态；如需查询账户余额，调用代收余额查询接口。

8. 常见问题

8.1 为什么接口返回参数校验失败？

请先检查请求是否为 POST application/json，以及 mchNo、reqTime、sign 和接口必填字段是否完整。平台接口不接收表单格式请求。

8.2 金额字段应该怎么传？

金额字段使用字符串类型，请按接口示例传入，例如 100.00。不要在签名前把金额转换成浮点数，避免精度或格式变化导致验签失败。

重要提示：代收订单可能因产品配置的匹配浮动范围影响产生金额调整，下单金额不一定等于实际应付金额。商户展示付款金额时，请以平台返回的 payableAmount 为准；回调入账或上分时，请以平台异步通知中的 actualReceivedAmount、fee、netAmount 等最终金额字段为准！

8.3 下单成功但没有支付页面链接怎么办？

以响应或查单中的 orderState/state 为准。若返回失败终态，表示本次没有可用支付页面链接；商户可使用新的商户订单号重新发起订单。

8.4 查单应该用哪个订单号？

查单只传 mchOrderNo。payOrderId 可用于商户侧记录和对账，但不要作为查单请求参数传入。

8.5 回调接收不到怎么办？

请检查 notifyUrl 是否公网可访问、是否使用有效 HTTPS 证书、是否返回 HTTP 2xx 和精确 SUCCESS。建议同时通过查单接口做补偿。

8.6 Python 服务收到的是表单参数怎么办？

平台推荐通知接收端按 application/json 解析。如果历史 Python 服务拿到的是 application/x-www-form-urlencoded，请先转换成普通字典或 JSON 对象，再按本文字段验签和处理。金额字段验签前请统一为十进制文本，不要转成浮点数。

8.7 本地调试出现 HTTPS 证书警告怎么办？

不要在生产环境关闭证书校验。请为接口域名配置可信证书，并使用能够通过证书验证的 HTTPS 地址。

代收接口文档 ​

1. 接口基础信息 ​

2. 通用参数 ​

2.1 通用请求参数 ​

2.2 通用响应结构 ​

3. 代收下单 ​

3.1 接口地址 ​

3.2 请求参数 ​

3.3 请求示例 ​

3.4 成功响应 ​

3.5 data 字段 ​

3.6 未获得支付页面链接的响应 ​

3.7 订单状态 ​

3.8 幂等规则 ​

4. 代收查单 ​

4.1 接口地址 ​

4.2 请求参数 ​

4.3 请求示例 ​

4.4 成功响应 ​

4.5 data 字段 ​

5. 代收余额查询 ​

5.1 接口地址 ​

5.2 请求参数 ​

5.3 请求示例 ​

5.4 成功响应 ​

5.5 data 字段 ​

6. 异步通知 ​

6.1 通知请求 ​

6.2 通知参数 ​

6.3 商户响应要求 ​

6.4 幂等处理建议 ​

7. 接入流程 ​

8. 常见问题 ​

8.1 为什么接口返回参数校验失败？ ​

8.2 金额字段应该怎么传？ ​

8.3 下单成功但没有支付页面链接怎么办？ ​

8.4 查单应该用哪个订单号？ ​

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

8.6 Python 服务收到的是表单参数怎么办？ ​

8.7 本地调试出现 HTTPS 证书警告怎么办？ ​

代收接口文档

1. 接口基础信息

2. 通用参数

2.1 通用请求参数

2.2 通用响应结构

3. 代收下单

3.1 接口地址

3.2 请求参数

3.3 请求示例

3.4 成功响应

3.5 `data` 字段

3.6 未获得支付页面链接的响应

3.7 订单状态

3.8 幂等规则

4. 代收查单

4.1 接口地址

4.2 请求参数

4.3 请求示例

4.4 成功响应

4.5 `data` 字段

5. 代收余额查询

5.1 接口地址

5.2 请求参数

5.3 请求示例

5.4 成功响应

5.5 `data` 字段

6. 异步通知

6.1 通知请求

6.2 通知参数

6.3 商户响应要求

6.4 幂等处理建议

7. 接入流程

8. 常见问题

8.1 为什么接口返回参数校验失败？

8.2 金额字段应该怎么传？

8.3 下单成功但没有支付页面链接怎么办？

8.4 查单应该用哪个订单号？

8.5 回调接收不到怎么办？

8.6 Python 服务收到的是表单参数怎么办？

8.7 本地调试出现 HTTPS 证书警告怎么办？