退款单笔查询API
请求地址
生产环境
https://merchserv.netpay.cmbchina.com/merchserv/BaseHttp.dll?QuerySettledRefundV2
测试环境
http://merchserv.cmburl.cn/merchserv/BaseHttp.dll?QuerySettledRefundV2
请求报文
报文的参数名:jsonRequestData,参数值JSON格式见下表
参数名称 | 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 |
查询类型 | type | String(1) | M | 查询类型 A:按银行退款流水号查单笔 B:按商户订单号+商户退款流水号+订单日期查单笔 C: 按商户订单号查对应的所有退款 | A |
type=A时,需上送以下信息: | |||||
银行退款流水号 | bankSerialNo | String(20) | C | 银行退款流水号长度不超过20位 | 20161101180000010001 |
订单日期 | date | String(8) | C | 商户原支付交易的订单日期,格式:yyyyMMdd | 20160624 |
type=B时,需上送以下信息: | |||||
商户订单号 | orderNo | String(32) | C | 商户原支付交易的订单号 | 9999000001 |
订单日期 | date | String(8) | C | 商户原支付交易的订单日期,格式:yyyyMMdd | 20160624 |
商户退款流水号 | merchantSerialNo | String(20) | C | 商户退款流水号长度不超过20位 | 20161101180000010001 |
type=C时,需上送以下信息: | |||||
商户订单号 | orderNo | String(32) | C | 商户原支付交易的订单号 | 9999000001 |
订单日期 | date | String(8) | C | 商户原支付交易的订单日期,格式:yyyyMMdd | 20160624 |
请求示例
1.json报文组织:
{ "version":"2.0", "sign":"DFAC9FF11DB20CFB75DD219694E8EAFA5C38D5658B0DC4CBAF39759FAF6A56C8", "signType":"SHA-256", "charset":"UTF-8", "reqData":{ "dateTime":"20161227161057", "branchNo":"0755", "merchantNo":"000054", "date":"20161105", "orderNo":"1336480523", "type":"C", "merchantSerialNo":"", "bankSerialNo":"" } }
2.表单组织:
<form action="请求地址" method="post" > <input type="hidden" name="jsonRequestData" value='以上json字符串' /> <input type="hidden" name="charset" value='utf-8' /> </form>
3.待签名字符串示例(未包含支付密钥):
bankSerialNo=&branchNo=0755&date=20161105&dateTime=20161227161057&merchantNo=000054&merchantSerialNo=&orderNo=1336480523&type=C
响应报文
参数名称 | JSON键值 | 类型(长度) | 必填 | 描述 | 示例 |
接口版本号 | 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 |
应答数据 | rsqData | ||||
处理结果 | rspCode | String | M | SUC0000:请求处理成功(不能仅通过该字段判断退款成功) 其他:请求处理失败 | SUC0000 |
详细信息 | rspMsg | String | C | 请求处理失败时返回错误信息 | |
响应时间 | dateTime | String(14) | M | 银行返回该数据的时间。 格式:yyyyMMddHHmmss | 20160624121212 |
返回条数 | dataCount | String | M | 本次查询返回条数 | 2 |
记录数据 | dataList | String | 每笔记录一行,每行以\r\n 结束。第一行为表头;从第二行起为数据记录;各参数以逗号和`符号分隔(`为标准键盘1 左边键的字符),字段顺序与表头一致。数据记录定义如下: | ||
分行号 | branchNo | String(4) | M | 商户分行号,4位数字 | 0755 |
商户号 | merchantNo | String(6) | M | 商户号,6位数字 | 000054 |
订单日期 | date | String(8) | M | 商户的订单日期,格式:yyyyMMdd | 20160624 |
订单号 | orderNo | String(32) | M | 商户的订单号 | 9999000001 |
银行退款流水号 | bankSerialNo | String(20) | M | 银行退款流水号 | 16280587500000000020 |
商户退款流水号 | merchantSerialNo | String(20) | O | 商户上送流水号 | 20161101180000010001 |
退款状态 | orderStatus | String(3) | M | 210:已直接退款 219:直接退款已受理 240:已授权退款 249:授权退款已受理 999:退款失败 | 210 |
币种 | currency | String(2) | M | 固定为:“10” | 10 |
退款金额 | amount | String | M | 格式:xxxx.xx | 0.01 |
费用金额 | fee | String | M | 格式:xxxx.xx | 0.01 |
银行受理日期 | acceptDate | String(8) | M | 格式:yyyyMMdd | 20160624 |
银行受理时间 | acceptTime | String(6) | M | 格式:HHmmss | 121201 |
银行处理日期 | bankDate | String(8) | M | 格式:yyyyMMdd | 20160624 |
银行处理时间 | bankTime | String(6) | M | 格式:HHmmss | 121201 |
退款描述 | desc | String(100) | O | 退款描述 | ABC123 |
实际退款金额 | 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)对于通过调用接口发起的退款,收到报文中rspCode=‘SUC0000’且orderStatus=‘210’,代表该笔退款处理成功且已经到账。
响应示例
1.正常json报文组织:
{ "version":"1.0", "charset":"utf-8", "sign":"见签名处理章节", "signType":"SHA-256", "rsqData":{ "rspCode":"SUC0000", "rspMsg":"", "dateTime":"20161227161149", "dataCount":"1", "dataList":"branchNo,`merchantNo,`date,`orderNo,`bankSerialNo,`merchantSerialNo,`orderStatus,`currency,`amount,`fee,`acceptDate,`acceptTime,`bankDate,`bankTime,`desc\r\n0755,`000054,`20161105,`1336480523,`16322749300000000020,`123456789,`210,`10,`0.01,`0.00,`20161227,`160330,`20161227,`160330,`aaa" } }
2.异常jason报文组织
{ "version":"1.0", "charset":"UTF-8", "sign":"见签名处理章节", "signType":"SHA-256", "rsqData":{ "rspCode":"MSS3207", "rspMsg":"MSS3207.无效银行退款流水号" } }
错误码
错误码 | 描述 | 解决方案 |
MSS9002 | 版本号错误 | Version固定为“1.0” |
MSS9003 | 签名算法错误 | 目前只支持“SHA-256” |
MSS9900 | 请求数据Json转换异常 | 校验并修改请求报文数据 |
MSS3411 | 签名错误 | 验证签名是否正确,请参考签名示例 |
MSS3812 | 无对应记录 | 原交易不存在。退款查询应建立轮询机制,返回该错误码,不能作为退款发起失败处理,需建立轮询机制5分钟内再次查询。再次查询后返回改错误码即可当退款请求发起失败处理。 |
USR0008 | 超过最大并行请求处理数限制 | 直连系统业务繁忙,稍后再试 |
MSS1016 | 分行号格式错误 | 分行号格式应为4位数字 |
MSS1017 | 商户号格式错误 | 操作员格式应为6位数字 |
MSS1022 | 订单日期或者时间格式错误 | 日期应为yyyyMMdd格式,时间应为yyyyMMddHHmmss格式 |
MSS1021 | 订单号式错误 | 订单号格式应为6-32位(含6和32),数字+字母(大小字母) |
MSS1102 | 退款流水号格式不正确 | 应为数字或字母组成,商户退款流水号长度不能超过32位,银行退款流水号长度不能超过20位 |
MSS3207 | 银行退款流水号格式不正确 | 银行退款流水号长度不超过20位 |
MSS3208 | 商户退款流水号格式不正确 | 商户退款流水号长度不超过20位 |
MSS3114 | 无效查询类型 | 查询类型只能为A/B/C |
MSS8011 | 主机无此商户定义 | 检查商户号、分行号是否正确 |
MSS2308 | 非法商户:商户参数未定义 | 检查商户数据是否正确 |
MSS3419 | 退款状态未知 | 请稍后重试 |
MSS3811 | 查询失败 | 具体失败原因参考报错信息 |