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[即 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");
待签名值
:money=2.0&outTradeNo=P12312321123&type=wechat&userId=test01&key=EWEFD123RGSRETYDFNGFGFGSHDFGH签名结果
:5E0AA05DD4BB4FE5AB65608123EBA591最终请求支付系统参数
:money=2.0&outTradeNo=P12312321123&type=wechat&userId=test01&sign=5E0AA05DD4BB4FE5AB65608123EBA591
商户登录商户系统后,通过安全中心查看或修改私钥key。
2. 退款申请
接口描述
业务通过统一退款接口发起退款申请
接口链接
URL地址:{payUrl}/api/refund/create_order
请求参数
字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
---|---|---|---|---|---|
商户ID | mchId | 是 | String(30) | 20001222 | 支付中心分配的商户号 |
支付订单号 | payOrderId | 是 | String(30) | P20160427210604000490 | 支付中心生成的原始订单号,与mchOrderNo二者传一即可 |
商户订单号 | mchOrderNo | 是 | String(30) | 20160427210604000490 | 商户生成的原始订单号,与payOrderId二者传一即可 |
商户退款单号 | mchRefundNo | 是 | String(30) | 20200727210612000129 | 商户生成的退款单号 |
退款金额 | amount | 是 | int | 100 | 退款金额,单位分 |
币种 | currency | 是 | String(3) | cny | 三位货币代码,人民币:cny |
客户端IP | clientIp | 否 | String(32) | 210.73.10.148 | 客户端IP地址 |
设备 | device | 否 | String(64) | ios10.3.1 | 客户端设备 |
附加参数 | extra | 否 | String(512) | 特定渠道发起时额外参数 | |
扩展参数1 | param1 | 否 | String(64) | 支付中心回调时原样返回 | |
扩展参数2 | param2 | 否 | String(64) | 支付中心回调时原样返回 | |
异步回调地址 | notifyUrl | 是 | String(128) | http://shop.xx.com/notify.htm | 退款结果异步回调URL |
渠道用户 | channelUser | 否 | String(256) | oIkQuwhPgPUgl-TvQ48_UUpZUwMs | 渠道用户信息 |
用户姓名 | userName | 否 | String(64) | 张三 | 用户姓名 |
备注 | remarkInfo | 否 | String(256) | 退款 | 备注信息 |
签名 | sign | 是 | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | 签名值,详见签名算法 |
响应结果
字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
---|---|---|---|---|---|
返回状态码 | retCode | 是 | String(16) | 0 | 0-处理成功,其他-处理有误,详见错误码 |
返回信息 | retMsg | 否 | String(128) | 签名失败 | 具体错误原因,例如:签名失败、参数格式校验错误 |
以下字段在retCode=0 时有返回
字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
---|---|---|---|---|---|
商户ID | mchId | 是 | String(30) | 20001222 | 支付中心分配的商户号 |
应用ID | appId | 否 | String(30) | wx390ee383939c4fb2 | 应用ID |
退款单号 | refundOrderId | 是 | String(30) | R01201907231119090520000 | 返回支付系统退款单号 |
商户退款单号 | mchRefundNo | 是 | String(30) | 20200727210612000129 | 商户生成的退款单号 |
退款金额 | refundAmount | 是 | int | 100 | 退款金额,单位分 |
订单状态 | status | 是 | String(3) | 2 | 退款状态:0-订单生成,1-退款中,2-退款成功,3-退款失败 |
渠道订单号 | channelOrderNo | 否 | String wx20170910211043fb206e92260071822007 | 对应的第三方单号 | |
退款成功时间 | refundSuccTime | 否 | Long | 1505049094262 | 退款成功时间,精确到毫秒 |
签名 | sign | 是 | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | 签名值,详见签名算法 |
3. 查询退款订单
接口描述
业务系统通过查询退款订单接口获取最新的退款订单状态,并根据状态结果进一步处理业务逻辑。
接口链接
URL地址:{payUrl}/api/refund/query_order
请求参数
字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
---|---|---|---|---|---|
商户ID | mchId | 是 | String(30) | 1000000010 | 支付中心分配的商户号 |
平台退款单号 | refundOrderId | 是 | String(30) | R20160427210604000490 | 支付中心生成的退款单号,与mchRefundNo二者传一即可 |
商户退款单号 | mchRefundNo | 是 | String(30) | 20160427210604000490 | 商户生成的订单号,与refundOrderId二者传一即可 |
签名 | sign | 是 | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | 签名值,详见签名算法 |
响应结果
字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
---|---|---|---|---|---|
返回状态码 | retCode | 是 | String(16) | 0 | 0-处理成功,其他-处理有误,详见错误码 |
返回信息 | retMsg | 否 | String(128) | 签名失败 | 具体错误原因,例如:签名失败、参数格式校验错误 |
以下字段在retCode=0 时有返回
字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
---|---|---|---|---|---|
商户ID | mchId | 是 | String(30) | 20001222 | 支付中心分配的商户号 |
应用ID | appId | 否 | String(30) | wx390ee383939c4fb2 | 应用ID |
商户退款单号 | mchRefundNo | 是 | String(30) | 20200727210612000129 | 商户生成的退款单号 |
退款金额 | refundAmount | 是 | int | 100 | 退款金额,单位分 |
订单状态 | status | 是 | String(3) | 2 | 退款状态:0-订单生成,1-退款中,2-退款成功,3-退款失败 |
渠道订单号 | channelOrderNo | 否 | String wx20170910211043fb206e92260071822007 | 对应的第三方单号 | |
退款成功时间 | refundSuccTime | 否 | Long | 1505049094262 | 退款成功时间,精确到毫秒 |
签名 | sign | 是 | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | 签名值,详见签名算法 |
4. 退款结果通知
接口描述
当退款完成时,支付中心会向商户的notifyUrl地址发起回调,通知退款状态。
接口链接
该链接是通过退款申请接口提交的参数notifyUrl设置,如果无法访问链接,业务系统将无法接收到支付中心的通知。
通知参数
字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
---|---|---|---|---|---|
商户ID | mchId | 是 | String(30) | 20001222 | 支付中心分配的商户号 |
应用ID | appId | 否 | String(30) | wx390ee383939c4fb2 | 应用ID |
退款单号 | refundOrderId | 是 | String(30) | R01201907231119090520000 | 返回支付系统退款单号 |
商户退款单号 | mchRefundNo | 是 | String(30) | 20200727210612000129 | 商户生成的退款单号 |
退款金额 | refundAmount | 是 | int | 100 | 退款金额,单位分 |
订单状态 | status | 是 | String(3) | 2 | 退款状态:0-订单生成,1-退款中,2-退款成功,3-退款失败 |
渠道订单号 | channelOrderNo | 否 | String wx20170910211043fb206e92260071822007 | 对应的第三方单号 | |
退款成功时间 | refundSuccTime | 否 | Long | 1505049094262 | 退款成功时间,精确到毫秒 |
扩展参数1 | param1 | 否 | String(64) | 支付中心回调时原样返回 | |
扩展参数2 | param2 | 否 | String(64) | 支付中心回调时原样返回 | |
退款成功时间 | refundSuccTime | 否 | Long | 1505049094262 | 退款成功时间,精确到毫秒 |
通知类型 | backType | 是 | int | 1 | 通知类型,1-前台通知,2-后台通知 |
签名 | sign | 是 | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | 签名值,详见签名算法 |
返回结果
业务系统处理后同步返回给支付中心,返回字符串 success 则表示成功,返回非success则表示处理失败,支付中心会再次通知业务系统。(通知频率为60/120/180/240/300,单位:秒)
注意:返回的字符串必须是小写,且前后不能有空格。