退款API

请求地址

生产环境
https://payment.ebank.cmbchina.com/NetPayment/BaseHttp.dll?DoRefund

测试环境
http://121.15.180.66:801/NetPayment_dl/BaseHttp.dll?DoRefund

请求报文

报文的参数名:jsonRequestData,参数值JSON格式见下表

参数 类型(长度) 必填 描述 示例
version String(3) M 接口版本号,固定为”1.0” 1.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) O
退款流水号,商户生成,同一笔订单内,同一退款流水号只能退款一次。
可用于防重复退款。
amount String(14) M 退款金额,格式xxxx.xx 0.01
desc String(100) O 退款描述
operatorNo String O 商户结账系统的操作员号 9999
encrypType String O
操作员密码加密算法,RC4:使用RC4算法对操作员密码进行加密,加密密钥为支付密钥。
DES:使用DES算法对操作员密码进行加密,加密密钥为商户支付密钥的前8位,不足8位则右补0.
空:默认不加密;
pwd String O
操作员登录密码。
使用encrypType算法加密后的密码
注意:加密后的密文必须转换为16进制字符串表示
BF6DC5D23519

示例报文

1.json报文组织:

{
    "version":"1.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"
    }
}

2.表单组织:

<form action="请求地址" method="post" >
    <input type="hidden" name="jsonRequestData" value='以上json字符串' /> 
</form>

3.待签名字符串示例(未包含支付密钥):
amount=0.01&branchNo=0755&date=20160629&dateTime=20160806150213&desc=&encrypType=RC4&merchantNo=000054&operatorNo=9999&orderNo=9999000042&pwd=BF6DC5D23519&refundSerialNo=201606250000001

响应报文

报文定义

参数 类型(长度) 必填 描述 示例
version String(3) M 接口版本号,固定为”1.0” 1.0
charset String(8) M 参数编码,固定为UTF-8 UTF-8
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

响应示例

1.正常json报文组织:

{
    "version":"1.0",
    "charset":"UTF-8",
    "rspData":{
        "rspCode":"SUC0000",
        "rspMsg":"",
        "dateTime":"20160806150217",
        "bankSerialNo":"16280672300000000010",
        "currency":"10",
        "amount":"0.01",
        "refundRefNo":"608061000002",
        "bankDate":"20160806",
        "bankTime":"150052"
    }
}

错误码

错误码 错误描述 解决方案
MSS3111 密码格式错误(空密码或超长) 明文密码或者密文密码解密后,密码长度不超过16位
MSS3112 解密失败 服务器解密失败,请检查密文密码是否正确
MSS3113 无效加密类型 只支持RC4/DES加密
MSS3804 直连退款失败 直连系统连接主机失败,稍后再试
MSS3414 描述内容超长 长度不超过100位
MSS3202 重复的直连退款请求,拒绝处理 请勿重复提交
MSS1016 分行号格式错误 分行号格式应为4位数字
MSS1017 商户号格式错误 商户号格式应为6位数字
MSS1019 操作员格式错误 操作员格式应为4位数字
MSS1020 金额格式错误 金额格式应xxxx.xx
MSS1021 订单号格式错误 订单号格式应为6位/10位数字
MSS1022 订单日期或者时间格式错误 日期应为yyyyMMdd格式,时间应为yyyyMMddHHmmss格式
MSS8011 主机无此商户定义 检查商户号、分行号是否正确

错误码

Q1. 退款时报错:“超出交易金额限制”原因以及如何解决?

有两种可能:

1、 累计退款超过原订单金额

2、 当天入账金额不够用于退款的

如果入账金额不够用,解决方法为:

1、 自己做一笔支付交易,然后用这笔支付交易的钱来完成退款。

2、 请分行授予一定的额度,在额度范围内可以分行垫付,第二天清算时才从企业账户中扣除

Q2. 退款什么时候到帐?

对于招行储蓄卡,退款资金实时到达客户的账户

对于招行信用卡,目前退款不会自动恢复额度。额度要到下一个账单日才能恢复。

对于非招行卡,退款取决于发卡行对代付交易的处理机制,是否实时入账不确定。

Q3. 退款有什么限制?

退款不能超过原订单金额

退款必须使用当天的收入来退。如果当天收入不足以退款,会报错“超出交易金额限制”

Q4. 需要退款,但当天收入不足怎么办?

以下两种方案都可以解决这一问题

1、 用自己的钱支付一笔。然后就能用这笔钱来退款了。

2、 请分行授予一定的额度,在额度范围内可以分行垫付,第二天清算时才从企业账户中扣除

Q5. 一个订单可以退好几次吗?

是的,一笔订单可以分多次退款,可以部分退款。

Q6. 直联退款失败,能否再次发起?

直联退款失败,不要再次发起,这样可能导致重复退款。

直联退款失败,不一定是因为退款没成功,还有其他的可能性,包括:

1、 通讯故障(退款请求已经发送到银行,然后网络出现问题,导致收不到结果)

2、 通讯超时(退款执行比较慢的情况下,可能出现)

因此,退款失败后,应该通过GetLastErr来获取失败原因,然后人工判断是否真的退款失败。

Q7. 退款后,订单状态会发生变化吗?

订单没有退款状态,退款和支付是两种不同的交易。退款要通过退款查询才能查到。执行过退款的订单,状态不会有任何改变,仍然是“已结帐”状态。

关于网站迁移公告


为提供更优质的开发技术支持,本网站已于2019年8月12日正式迁移至新域名http://openhome.cmbchina.com/paynew/pay/Home,敬请访问并收藏。原网站域名已停止更新维护,请以新网站提供的文档信息为准。

由此给您带来的不便,敬请谅解。


招商银行一网通支付技术支持小组

2019年8月12日