退款API
请求地址
生产环境
https://merchserv.netpay.cmbchina.com/merchserv/BaseHttp.dll?DoRefundV2
测试环境
http://merchserv.cmburl.cn/merchserv/BaseHttp.dll?DoRefundV2
请求报文
报文的参数名:jsonRequestData,参数值JSON格式见下表
参数 | 类型(长度) | 必填 | 描述 | 示例 |
version | String(3) | M | 接口版本号,固定为“2.0” | 2.0 |
charset | String(8) | M | 参数编码,固定为“UTF-8” | UTF-8 |
sign | String | M | 报文签名,对reqData内的数据进行签名 | |
signType | String | M | 签名算法,固定为“SHA-256” | SHA-256 |
reqData | 请求数据 | |||
dateTime | String(14) | M | 商户发起该请求的当前时间,精确到秒。 格式:yyyyMMddHHmmss | 20160623120100 |
branchNo | String(4) | M | 商户分行号,4位数字 | 0755 |
merchantNo | String(6) | M | 商户号,6位数字 | 000054 |
date | String(8) | M | 商户订单日期,支付时的订单日期 格式:yyyyMMdd | 20160624 |
orderNo | String(32) | M | 商户订单号,支付时的订单号 | 9999000001 |
refundSerialNo | String(20) | M | 退款流水号,商户生成,同一笔订单内,同一退款流水号只能退款一次。可用于防重复退款。 | |
amount | String(14) | M | 退款金额,格式xxxx.xx | 0.01 |
desc | String(100) | O | 退款描述 | |
clientIP | String | O | 用户ip | 使用商户密钥进行SM4加密 |
mac | String | O | mac地址 | 使用商户密钥进行SM4加密 |
operatorNo | String | O | 商户结账系统的操作员号,选填,若填了则会对操作员号和密码进行校验,若不填则不校验。 注意:2019.01.01以后接入的商户默认“不填” | 9999 |
pwd | String | O | 旧结账系统的操作员登录密码。使用encrypType算法加密后的密码,加密后的密文必须转换为16进制字符串表示。 注意:2019.01.01以后接入的商户默认“不填” | BF6DC5D23519 |
refundMode | String(1) | O | 退款标识字段 空/“A”:按照订单金额发起退款(适用于自动清算/手工清算优惠交易) | 可不传或refundMode=""; refundMode="A" |
注意:
1. 交易时间超过一年的订单无法提交退款。
2. 支付退款支持单笔交易分多次退款,多次退款需要提交原支付订单的商户订单号,并设置不同的退款流水号。申请退款总金额不能超过订单金额。 一笔退款失败后重新提交,请不要更换退款流水号,请使用原商户退款流水号。
3. 默认请发起订单金额进行退款,对于部分金额退款,将按照发起金额/原交易订单金额计算退款比例。
请求示例
1.json报文组织:
{ "version":"2.0", "charset":"UTF-8", "sign":"见签名处理章节", "signType":"SHA-256", "reqData": { "dateTime":"20160806150213", "branchNo":"0755", "merchantNo":"000054", "date":"20160629", "orderNo":"9999000042", "amount":"0.01", "desc":"", "refundSerialNo":"201606250000001", "operatorNo":"9999", "encrypType":"RC4", "pwd":"BF6DC5D23519", "refundMode":"A" } }
2.表单组织:
<form action="请求地址" method="post"> <input type="hidden" name="jsonRequestData" value='以上json字符串' /> <input type="hidden" name="charset" value=’utf-8’ /> </form>
3.待签名字符串示例(未包含支付密钥):
amount=0.01&branchNo=0755&date=20160629&dateTime=20160806150213&desc=&encrypType=RC4&merchantNo=000054&operatorNo=9999&orderNo=9999000042&pwd=BF6DC5D23519&refundSerialNo=201606250000001&refundMode=A
响应报文
参数 | 类型(长度) | 必填 | 描述 | 示例 |
version | String(3) | M | 接口版本号,固定为“2.0” | 2.0 |
charset | String(8) | M | 参数编码,固定为“UTF-8” | UTF-8 |
sign | String | M | 报文签名,使用商户支付密钥对rspData内的数据进行验签 | |
signType | String | M | 签名算法,固定为”SHA-256” | SHA-256 |
rspData | 请求数据 | |||
rspCode | String | M | 处理结果,SUC0000:请求处理成功 其他:请求处理失败 | SUC0000 |
rspMsg | String | M | 详细信息,请求处理失败时返回错误描述 | |
dateTime | String(14) | M | 响应时间,银行返回该数据的时间 格式:yyyyMMddHHmmss | 20160624121212 |
bankSerialNo | String(20) | M | 银行的退款流水号 | 16280672300000000010 |
currency | String(2) | M | 退款币种,固定为:“10” | 10 |
amount | String | M | 退款金额,格式:xxxx.xx | 0.01 |
refundRefNo | String | O | 银行的退款参考号 | 608061000002 |
bankDate | String(8) | M | 退款受理日期 格式:yyyyMMdd | 20160624 |
bankTime | String(6) | M | 退款受理时间 格式:HHmmss | 121201 |
refundSerialNo | String | M | 商户上送流水号 | 123456789 |
settleAmount | String | M | 实际退款金额,格式:xxxx.xx | 0.01 |
discountAmount | String | M | 退回优惠金额,格式:xxxx.xx | 0.01 |
以下字段联系招行配置控制参数后返回(默认不返回): | ||||
uniqueUserID | String(30) | C | 支付用户ID,由身份证+姓名生成(推荐使用) | UQwanCunLbp6cl1RbDFODrhLrAa48= |
expandUserID | String(30) | C | 一网通用户ID,由一网通ID生成(招行一网通用户的身份标识) | EUfirwdVQVKhffJmjQhMod0dS6GYY= |
注意:
1. 如果因为异常原因没有收到同步响应报文,请调用退款查询API确认退款状态。
响应示例
1.正常json报文组织:
{ "version":"2.0", "charset":"UTF-8", "sign":"见签名处理章节", "signType":"SHA-256", "rspData":{ "rspCode":"SUC0000", "rspMsg":"", "dateTime":"20160806150217", "bankSerialNo":"16280672300000000010", "currency":"10", "amount":"0.01", "refundRefNo":"608061000002", "bankDate":"20160806", "bankTime":"150052" “refundSerialNo”:”123456789” “settleAmount”:”0.01” “discountAmount”:”0.01” } }
错误码
错误码 | 描述 | 解决方案 |
MSS9900 | 请求数据Json转换异常 | 检验并修改请求报文数据 |
MSS9002 | 版本号错误 | Version固定为“1.0” |
MSS9003 | 签名算法错误 | 目前仅支持“SHA-256” |
MSS3112 | 操作员密码解密失败 | 检查操作员密码及加密方式 |
MSS3113 | 无效加密类型 | 只支持RC4/DES加密 |
MSS3411 | 签名错误 | 验证签名是否正确,请参考签名示例 |
MSS3414 | 描述内容超长 | 长度不超过100位 |
MSS1016 | 分行号格式错误 | 分行号格式应为4位数字 |
MSS1017 | 商户号格式错误 | 商户号格式应为6位数字 |
MSS1019 | 操作员格式错误 | 操作员格式应为4位数字 |
MSS1020 | 金额格式错误 | 金额格式应xxxx.xx |
MSS1021 | 订单号格式错误 | 订单号格式应为6位/10位数字 |
MSS1022 | 订单日期或者时间格式错误 | 日期应为yyyyMMdd格式, 时间应为yyyyMMddHHmmss格式 |
MSS8011 | 主机无此商户定义 | 检查商户号、分行号是否正确 |
MSS2038 | 非法商户:商户参数未定义 | 检查商户数据是否正确 |
MSS1104 | 请求时间延迟 | 检查dateTime参数,不能早于服务器时间前30分钟 |
MSS2009 | 该商户不允许进行直连退款 | 请检查商户管理系统配置参数 |
MSS1102 | 退款流水号格式不正确 | 因为数字或字母组成,长度不能超过32位 |
MSS3118 | 无效退款模式 | 退款模式只能为空/A/B |
MSS3815 | 退款失败—无此订单 | 检查orderNo是否正确或原支付交易是否成功 |
MSS3816 | 退款失败—退款金额超限 | 检查amount是否正确 |
MSS3817 | 退款状态未知 | 请调用查询接口确认退款结果 |
MSS3804 | 退款失败 | 具体失败原因参考报错信息 |