支付接口文档

1. 协议规则

传输方式：采用HTTP传输(生产环境建议HTTPS)
提交方式：采用POST/GET方式提交
字符编码：UTF-8
签名算法：MD5

1.1 参数规范

交易金额：默认为人民币交易，单位为分，参数值不能带小数。

1.2 安全规范

签名算法

签名生成的通用步骤如下

第一步：设所有发送或者接收到的数据为集合M，将集合M内非空参数值的参数按照参数名ASCII码从小到大排序（字典序），使用URL键值对的格式（即key1=value1&key2=value2…）拼接成字符串stringA。

特别注意以下重要规则：

◆ 参数名ASCII码从小到大排序（字典序）；

◆ 如果参数的值为空不参与签名；

◆ 参数名区分大小写；

◆ 验证调用返回或支付中心主动通知签名时，传送的sign参数不参与签名，将生成的签名与该sign值作校验。

◆ 支付中心接口可能增加字段，验证签名时必须支持增加的扩展字段

第二步：在stringA最后拼接上key得到stringSignTemp字符串，并对stringSignTemp进行MD5运算，再将得到的字符串所有字符转换为大写，得到sign值signValue。

如请求支付系统参数如下：

    Map signMap = new HashMap<>();
    signMap.put("userId", "test01");
    signMap.put("type", "wechat");
    signMap.put("money", Double.valueOf(2));
    signMap.put("remark", "");
    signMap.put("outTradeNo", "P12312321123");

待签名值：amount=1&appId=2&body=3&extra=5&mchId=6&mchOrderNo=7&notifyUrl=8&productId=9&returnUrl=9&subject=10&key=秘钥，参考签名算法
签名结果：5E0AA05DD4BB4FE5AB65608123EBA591

商户登录商户系统后，通过安全中心查看或修改私钥key。

2. 统一下单

接口描述

业务通过统一下单接口可以发起任意三方支付渠道的支付订单。业务系统不必关心该如何调用三方支付，统一下单接口会根据业务系统选择的支付渠道ID，选择对应支付渠道的支付产品，发起下单请求，然后响应给业务系统支付请求所需参数。

接口链接

URL地址：https://域名(联系运营人员获取)/api/pay/create_order
Content-Type：application/x-www-form-urlencoded
Method：POST

请求参数

字段名 变量名 必填 类型 示例值 描述
商户ID mchId 是 long 20001222 分配的商户号
支付产品ID productId 是 int 8000 支付产品ID，详见5、支付产品
商户订单号 mchOrderNo 是 String(30) 20160427210604000490 商户生成的订单号
支付金额 amount 是 int 100 支付金额,单位分
商品主题 subject 是 String(64) 测试商品1 商品主题
商品描述信息 body 是 String(256) 测试商品描述 商品描述信息
支付结果后台回调URL notifyUrl 是 String(128) http://shop.xxx.org/notify.htm 支付结果异步回调URL（NO_NOTIFY则表示不回调）
应用ID appId 否 String(32) 0ae8be35ff634e2abe94f5f32f6d5c4f 该商户创建的应用对应的ID可以不需要这个参数
客户端IP clientIp 否 String(128) 210.73.10.148 客户端IP地址
设备 device 否 String(64) pc：pc浏览器 mobile：移动设备 客户端设备
银行编码 bankCode 否 String(512) 支付银行编码
支付结果前端跳转URL returnUrl 否 String(128) http://shop.xxx.org/return.htm 支付结果同步回调URL
扩展参数1 param1 否 String(512) 支付中心回调时会原样返回
扩展参数2 param2 否 String(512) 支付中心回调时会原样返回
扩展参数3 param3 否 String(512) 支付中心回调时会原样返回
附加参数 extra 否 String(512) 特定渠道发起时额外参数。如对接卡转卡需要给付款人姓名
商户来源商家号 mchSourceNo 否 String(512) test 商户来源商家号
签名 sign 是 String(32) C380BEC2BFD727A4B6845133519F3AD6 amount=1&appId=2&body=3&extra=5&mchId=6&mchOrderNo=7&notifyUrl=8&productId=9&returnUrl=9&subject=10&key=秘钥，参考签名算法

返回结果

Content-Type: application/json

字段名 变量名 必填 类型 示例值 描述
返回状态码 retCode 是 String(16) SUCCESS SUCCESS/FAIL此字段标识是否成功
返回信息 retMsg 否 String(128) 签名失败 返回信息，如非空，为错误原因 签名失败 参数格式校验错误
以下字段在retCode为SUCCESS的时候有返回
字段名 变量名 必填 类型 示例值 描述
签名 sign 是 String(32) C380BEC2BFD727A4B6845133519F3AD6 签名值，详见签名算法
支付订单号 payOrderId 是 String(32) 20160427210604000490 支付中心生成的订单号
支付方式 payMethod 是 String(32) formJump 当payMethod字段为formJump时，请获取payUrl字段的链接地址进行跳转，如：window.location.href=data.payUrl
当payMethod为codeImg时，请获取codeUrl的二维码地址进行展示
当payMethod字段为formData时，请将content字段的form表单内容写入浏览器空白页面进行展示，如：document.write(data.content)
支付参数 data 是 JSONObject {"matchCode":"1234","amount":10000,"bankNumber":"27879797987","bankBranch":"支行","bankUsername":"王红","bankName":"北京银行","codeUrl":"https://img.vietqr.io/image/SHB-5801561969-print.jpg?amount=100000.00&addInfo=00DBT0&accountName=CTY+TNHH+TU+VAN+TAN+KIET","payUrl":"http://localhsot:8089/xxx?orderNo=1547228975296675840","content":"xxx","qrCode":"二维码流数据"} 该字段返回JSON格式数据payUrl是返回了渠道自己本身的收银台，codeUrl是返回了二维码链接地址可以直接在界面展示，如果codeUrl参数是空就直接获取qrCode这个参数，qrCode是返回了二维码流数据

3. 查询支付订单

接口描述

业务系统通过查询支付订单接口获取最新的支付订单状态，并根据状态结果进一步处理业务逻辑。

接口链接

URL地址：https://域名(联系运营人员获取)/api/pay/query_order
Content-Type：application/x-www-form-urlencoded
Method：POST

请求参数

字段名 变量名 必填 类型 示例值 描述
商户ID mchId 是 String(30) 1000000010 支付中心分配的商户号
应用ID appId 否 String(32) 0ae8be35ff634e2abe94f5f32f6d5c4f 该商户创建的应用对应的ID可以不需要这个参数
支付订单号 payOrderId 是 String(30) P20160427210604000490 支付中心生成的订单号，与mchOrderNo二者传一即可
商户订单号 mchOrderNo 是 String(30) 20160427210604000490 商户生成的订单号，与payOrderId二者传一即可
是否执行回调 executeNotify 否 Boolean true 是否执行回调，如果为true，则支付中心会再次向商户发起一次回调，如果为false则不会发起
签名 sign 是 String(32) C380BEC2BFD727A4B6845133519F3AD6 签名值，详见签名算法

返回结果

Content-Type: application/json

字段名 变量名 必填 类型 示例值 描述
返回状态码 retCode 是 String(16) SUCCESS SUCCESS/FAIL此字段标识是否成功
返回信息 retMsg 否 String(128) 签名失败 返回信息，如非空，为错误原因 签名失败 参数格式校验错误
以下字段在retCode为SUCCESS的时候有返回
字段名 变量名 必填 类型 示例值 描述
商户ID mchId 是 long(30) 20001222 支付中心分配的商户号
应用ID appId 否 String(32) 0ae8be35ff634e2abe94f5f32f6d5c4f 该商户创建的应用对应的ID可以不需要这个参数
支付产品ID productId 是 int 8001 支付产品ID
支付订单号 payOrderId 是 String(30) P20160427210604000490 支付中心生成的订单号
商户订单号 mchOrderNo 是 String(30) 20160427210604000490 商户生成的订单号
支付金额 amount 是 int 100 支付金额,单位分
币种 currency 是 String(3) cny 三位货币代码,人民币:cny
状态 status 是 int 1 支付状态,0-订单生成,1-支付中,2-支付成功,3-业务处理完成
渠道用户ID channelUser 否 String(64) xxx@126.com 渠道测支付时使用的用户ID
渠道订单号 channelOrderNo 否 String wx20170910211043fb206e92260071822007 对应的第三方支付订单号
渠道数据包 channelAttach 否 String {"bank_type":"CMB_DEBIT","trade_type":"pay.weixin.micropay"} 支付渠道数据包
支付成功时间 paySuccTime 否 Long 1505049094262 支付成功时间

4. 支付结果通知

接口描述

当支付订单处理完成后，支付系统会通过该接口向商户发起通知。

接口链接

该链接是通过统一下单接口提交的参数notifyUrl设置，如果无法访问链接，业务系统将无法接收到支付中心的通知。
Content-Type：application/x-www-form-urlencoded
Method：POST

通知参数（QueryString）

字段名 变量名 必填 类型 示例值 描述
支付订单号 payOrderId 是 String(30) P20160427210604000490 支付中心生成的订单号
商户ID mchId 是 String(30) 20001222 支付中心分配的商户号
应用ID appId 否 String(32) 0ae8be35ff634e2abe94f5f32f6d5c4f 该商户创建的应用对应的ID可以不需要这个参数
支付产品ID productId 是 int 8001 支付产品ID
商户订单号 mchOrderNo 是 String(30) 20160427210604000490 商户生成的订单号
银行编码 bankCode 否 String(512) 银行编码
支付金额 amount 是 int 100 支付金额,单位分
入账金额 income 是 int 100 扣除手续费后的入账金额,单位分
状态 status 是 int 1 支付状态,0-订单生成,1-支付中,2-支付成功,3-业务处理完成
渠道订单号 channelOrderNo 否 String(64) wx2016081611532915ae15beab0167893571 三方支付渠道订单号
扩展参数1 param1 否 String(512) 支付中心回调时会原样返回
扩展参数2 param2 否 String(512) 支付中心回调时会原样返回
扩展参数3 param3 否 String(512) 支付中心回调时会原样返回
支付成功时间 paySuccTime 是 long 精确到毫秒
通知类型 backType 是 int 1 通知类型，1-前台通知，2-后台通知
签名 sign 是 String(32) C380BEC2BFD727A4B6845133519F3AD6 签名值，详见签名算法进行重小到大排序然后进行md5加密amount=1&appId=2&backType=3&income=4&mchId=5&mchOrderNo=6&payOrderId=7&paySuccTime=8&productId=9&status=10&key=秘钥

返回结果

业务系统处理后同步返回给支付中心，返回字符串 success 则表示成功，返回非success则表示处理失败，支付中心会再次通知业务系统。（通知频率为60/120/180/240/300,单位：秒）

5. 申请结算

接口描述

结算功能是通过接口结算给商户，申请成功并不代表代付成功。支付中心将通过notifyUrl进行回调通知或商户系统客户主动发起结算查询，以查询到的最终结果确定结算是否成功。

接口链接

URL地址：http://域名(联系运营人员获取)/api/settlement/create_order
Content-Type：application/x-www-form-urlencoded
Method：POST

请求参数

字段名 变量名 必填 类型 示例值 描述
商户ID mchId 是 long 20001222 分配的商户号
商户结算单号 mchOrderNo 是 String(30) 32154135131151313 商户结算订单号
结算金额 amount 是 int 8000 代付金额,单位分
收款人账户名 accountName 是 String(64) manager 收款人账户名
收款人账户号 accountNo 是 Number 6222020200098541458 收款人账户号
银行名称 bankName 是 String(32) 北京上地支行 开户行网点
开户行名称 bankNetName 是 String(32) 北京上地支行 开户行网点
请求时间 reqTime 是 String(20) 20181009171032 请求发起时间,时间格式:yyyyMMddHHmmss
结算结果后台回调URL notifyUrl 是 String(128) http://shop.xxx.org/notify.htm 结算结果异步回调URL（NO_NOTIFY则表示不回调）
开户行所在省份 province 否 String(32) 北京 开户行所在省份
开户行所在市 city 否 String(32) 北京 开户行所在市
商户来源商家号 mchSourceNo 否 String(512) test 商户来源商家号
备注 remark 否 String(128) 代付1000元 备注
签名 sign 是 String(32) C380BEC2BFD727A4B6845133519F3AD6 签名值，详见签名算法

返回结果

Content-Type: application/json

字段名 变量名 必填 类型 示例值 描述
返回状态码 retCode 是 String(16) SUCCESS SUCCESS/FAIL此字段标识是否成功
返回信息 retMsg 是 String(128) 签名失败 返回信息，如非空，为错误原因 签名失败 参数格式校验错误
以下字段在retCode为SUCCESS的时候有返回
字段名 变量名 必填 类型 示例值 描述
平台结算单号 settOrderId 是 String(30) S01201903291018050180000 支付系统生成的代付订单号
商户结算单号 thirdOrderId 是 String(30) 3215413513115131312 支付系统生成的代付订单号
结算状态 status 是 String 1 1-等待审核,2-已审核,3-审核不通过,4-打款中,5-打款成功,6-打款失败
签名 sign 是 String(32) 6012FB85432A4BBAA309985A1C054219 签名值

6. 结算结果通知

接口描述

当结算处理完成(结算单状态变更成审核不通过,打款成功,打款失败)后，支付系统会通过该接口向商户发起通知。

接口链接

该链接是通过结算申请接口提交的参数notifyUrl设置，如果设置为NO_NOTIFY或notifyUrl无法访问链接，业务系统将无法接收到支付中心的通知。
Content-Type：application/json
Method：POST

通知参数

字段名 变量名 必填 类型 示例值 描述
商户结算单号 mchOrderNo 是 String(30) 32154135131151313 商户结算订单号
平台结算单号 settleOrderId 是 String(30) s32154135131151313 商户结算订单号
结算金额 amount 是 int 8000 结算金额,单位分
结算状态 status 是 String 1 3-审核不通过,5-打款成功,6-打款失败
签名 sign 是 String(32) 3B166CA71811D4A0FEC25D511A365ED3 签名值，详见签名算法

返回结果

业务系统处理后同步返回给支付中心，返回字符串 success 则表示成功，返回非success则表示处理失败，支付中心会再次通知业务系统。（通知频率为60/120/180/240/300,单位：秒）

7. 结算查询

接口描述

商户通过该接口查询结算订单结果，并根据状态结果进一步处理业务逻辑。

接口链接

URL地址：http://域名(联系运营人员获取)/api/settlement/query_order
Content-Type：application/x-www-form-urlencoded
Method：POST

请求参数

字段名 变量名 必填 类型 示例值 描述
商户ID mchId 是 long 1000000010 分配的商户号
商户订单号 mchOrderNo 是 String(30) AP1538919309174 商户生成的订单号，与settleOrderId二者传一即可
平台结算订单号 settleOrderId 是 String(30) G01201810070935094340418 支付中心生成的订单号，与mchOrderNo二者传一即可
签名 sign 是 String(32) C380BEC2BFD727A4B6845133519F3AD6 签名值，详见签名算法

返回结果

Content-Type: application/json

字段名 变量名 必填 类型 示例值 描述
返回状态码 retCode 是 String(16) SUCCESS SUCCESS/FAIL此字段标识是否成功
返回信息 retMsg 否 String(128) 签名失败 返回信息，如非空，为错误原因 签名失败 参数格式校验错误
以下字段在retCode为SUCCESS的时候有返回
字段名 变量名 必填 类型 示例值 描述
商户ID mchId 是 long(30) 20001222 支付中心分配的商户号
商户结算单号 mchSettleOrderNo 是 String(30) 32154135131151313 商户结算订单号
平台结算单号 settleOrderId 是 String(30) s32154135131151313 商户结算订单号
结算金额 amount 是 int 8000 代付金额,单位分
结算状态 status 是 String 1 1-等待审核,2-已审核,3-审核不通过,4-打款中,5-打款成功,6-打款失败
收款人账户名 accountName 是 String(64) manager 收款人账户名
收款人账户号 accountNo 是 Number 6222020200098541458 收款人账户号
备注 remark 是 String(128) 代付1000元 备注

8. UTR补单

接口描述

商户通过该接口补单，并根据状态结果进一步处理业务逻辑。

接口链接

URL地址：http://域名(联系运营人员获取)/api/check/utr
Content-Type：application/x-www-form-urlencoded
Method：POST

请求参数

字段名 变量名 必填 类型 示例值 描述
商户ID mchId 是 long 1000000010 分配的商户号
商户订单号 mchOrderNo 是 String(30) AP1538919309174 商户生成的订单号
UTRID utrId 是 String(30) G01201810070935094340418 UTR补单ID
签名 sign 是 String(32) C380BEC2BFD727A4B6845133519F3AD6 签名值，详见签名算法

返回结果

Content-Type: application/json

字段名 变量名 必填 类型 示例值 描述
返回状态码 retCode 是 String(16) SUCCESS SUCCESS/FAIL此字段标识是否成功
返回信息 retMsg 否 String(128) 签名失败 返回信息，如非空，为错误原因 签名失败 参数格式校验错误

9. 支付产品

请登录商户后台查询已开通的支付产品或联系运营人员获取

10. 错误码

错误码值 描述 原因 解决方案
0010 系统错误 系统超时或异常 系统异常，请用相同参数重新调用