支付平台 API 对接文档

本文档提供支付平台 HTTP API 的对接说明，包括签名方式、创建订单、订单回调、查询订单和余额查询的接口规范。接口使用 POST 方法，具体 Content-Type 请参见各接口说明。

1. 签名方式

签名用于验证请求的完整性和合法性，签名算法为 MD5。以下为签名生成步骤：

字典排序：将所有非空参数（除 sign 外）按键名进行字典序排序，拼接为 URL 键值对字符串（格式：k1=v1&k2=v2），使用 UTF-8 编码。
拼接密钥：在步骤 1 的字符串末尾追加密钥，格式为：k1=v1&k2=v2&key=密钥值。密钥值为商户对应的 mchValue，需通过数据库查询获取。
MD5 运算：对步骤 2 的字符串进行 MD5 运算，得到签名值，并转换为小写。

注意：所有参与签名的非空参数必须包含在签名字符串中，签名结果为小写。

示例：

参数：busId=1001&orderNo=123456&mchValue=abc123

排序拼接：busId=1001&orderNo=123456
追加密钥：busId=1001&orderNo=123456&key=abc123
MD5 运算：sign=md5(busId=1001&orderNo=123456&key=abc123).toLowerCase()

2. 创建订单

请求方法：POST

Content-Type：application/x-www-form-urlencoded

请求地址：由平台提供

2.1 请求参数

参数名称	参数含义	是否必填	参与签名
busId	商户号	是	是
orderNo	商户订单号	是	是
channelProductId	产品编码	是	是
orderAmount	订单金额（元）	是	是
notifyUrl	服务端通知地址	是	是
callbackUrl	页面跳转通知地址	是	是
sign	MD5 签名	是	否
subject	会员姓名（代付业务格式：姓名\|卡号）	否	是

注意：对于代付业务，subject 需按 姓名|卡号 格式提供。

2.2 返回结果

返回格式：JSON

参数名称	参数含义
code	“0” 表示支付成功，其余表示获取支付链接失败
data	支付链接
msg	信息

成功返回示例：

{
    "code": "0",
    "data": "https://pay.example.com/pay?orderId=123456",
    "msg": "订单创建成功"
}

失败返回示例：

{
    "code": "1001",
    "data": null,
    "msg": "订单号重复"
}

3. 订单回调通知

请求方法：POST

Content-Type：application/x-www-form-urlencoded

仅成功订单会触发回调，商户需验证签名，验证成功后返回大写 OK。

3.1 回调参数

参数名称	参数含义	是否必填	参与签名
busId	商户号	是	是
orderNo	商户订单号	是	是
channelProductId	产品编码	是	是
orderAmount	订单金额（元）	是	是
notifyUrl	服务端通知地址	是	是
callbackUrl	页面跳转通知地址	是	是
sign	MD5 签名	是	否

3.2 返回要求

商户验证签名成功后，需返回大写字符串 OK（无 JSON 包装）。

回调请求示例：

busId=1001&orderNo=123456&channelProductId=PROD001&orderAmount=100.00¬ifyUrl=https://merchant.com/notify&callbackUrl=https://merchant.com/callback&sign=abc123def456

返回示例：

OK

4. 查询订单

请求方法：POST

Content-Type：application/x-www-form-urlencoded

请求地址：由平台提供

4.1 请求参数

参数名称	参数含义	是否必填	参与签名
busId	商户号	是	是
orderNo	商户订单号	是	是
sign	MD5 签名	是	否

4.2 返回结果

返回格式：JSON

参数名称	参数含义
busId	商户号
orderId	平台订单号
orderAmount	订单金额（元）
orderSuccessTime	支付成功时间
orderStatus	订单状态： -1=失败（超时交易关闭） 1=未处理 2或3=成功（已支付） 5=通道无码
shortMsg	订单状态简要提示信息，例如 `交易失败，详情请咨询您的发卡行`

返回示例：

{
    "busId": "1001",
    "orderId": "P123456789",
    "orderAmount": "100.00",
    "orderSuccessTime": "2025-06-13 12:00:00",
    "orderStatus": 2,
    "shortMsg": "交易失败，详情请咨询您的发卡行"
}

5. 余额查询

请求方法：POST

Content-Type：application/json

请求地址：由平台提供（如 https://ip:port/api/admin/pub/mch/preBalance）

商户通过该接口查询净预付余额（实时剩余预付）。

5.1 请求参数

参数名称	参数含义	是否必填	参与签名
mchId	商户号	是	是
reqTime	请求时间（13位时间戳）	是	是
sign	MD5 签名	是	否

5.2 返回结果

返回格式：JSON

参数名称	参数含义
code	返回标记：0=成功，1=失败
msg	返回信息
data	数据对象，包含以下字段： - `mchId`：商户号 - `netPrepaidBalance`：净预付余额（元）

成功返回示例：

{
    "code": 0,
    "msg": "查询成功",
    "data": {
        "mchId": "M1623984572",
        "netPrepaidBalance": 5000.00
    }
}

失败返回示例：

{
    "code": 1,
    "msg": "签名验证失败",
    "data": null
}

请求示例：

curl -X POST https://ip:port/api/admin/pub/mch/preBalance \
-H "Content-Type: application/json" \
-d '{
    "mchId": "M1623984572",
    "reqTime": 1622016572190,
    "sign": "694da7a446ab4b1d9ceea7e5614694f4"
}'

签名示例：

参数：mchId=M1623984572&reqTime=1622016572190&mchValue=abc123

排序拼接：mchId=M1623984572&reqTime=1622016572190
追加密钥：mchId=M1623984572&reqTime=1622016572190&key=abc123
MD5 运算：sign=md5(mchId=M1623984572&reqTime=1622016572190&key=abc123).toLowerCase()

6. 注意事项

所有接口请求和响应均使用 UTF-8 编码。
签名计算时，需确保参数值的顺序按字典序排列，且值不为空。
orderNo 需保证唯一性，重复提交可能导致错误。
回调通知仅针对成功订单，商户需确保 notifyUrl 可公网访问。
查询订单和余额查询接口用于确认订单状态或账户余额，建议在未收到回调或需核查时主动调用。
签名密钥（mchValue）需通过商户号查询数据库获取，确保正确性。

7. 联系方式

如有疑问，请联系技术支持团队：

电报：@leyun
电话：888-888-8888