小程序冻结

退款API

请求地址

生产环境
https://merchserv.netpay.cmbchina.com/merchserv/BaseHttp.dll?DoRefundV2

测试环境
http://121.15.180.66:801/netpayment_directlink_nosession/BaseHttp.dll?DoRefundV2

请求报文

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

参数类型(长度)必填描述示例
versionString(3)M接口版本号,固定为“2.0”2.0
charsetString(8)M参数编码,固定为“UTF-8”UTF-8
signStringM报文签名,对reqData内的数据进行签名
signTypeStringM签名算法,固定为“SHA-256”SHA-256
reqData请求数据
dateTimeString(14)M商户发起该请求的当前时间,精确到秒。 格式:yyyyMMddHHmmss20160623120100
branchNoString(4)M商户分行号,4位数字0755
merchantNoString(6)M商户号,6位数字000054
dateString(8)M商户订单日期,冻结交易的订单日期
格式:yyyyMMdd
20160624
orderNoString(32)M商户订单号,冻结交易的订单号9999000001
refundSerialNoString(20)M退款流水号,商户生成,同一笔订单内,同一退款流水号只能退款一次。可用于防重复退款。
amountString(14)M退款金额,格式xxxx.xx0.01
descString(100)O退款描述
operatorNoStringO商户结账系统的操作员号,选填,若填了则会对操作员号和密码进行校验,若不填则不校验。
注意:2019.01.01以后接入的商户默认“不填”
9999
encrypTypeStringO操作员密码加密算法,RC4:使用RC4算法对操作员密码进行加密,加密密钥为支付密钥。DES:使用DES算法对操作员密码进行加密,加密密钥为商户支付密钥的前8位,不足8位则右补0。空:默认不加密。
注意:2019.01.01以后接入的商户默认“不填”

pwdStringO旧结账系统的操作员登录密码。使用encrypType算法加密后的密码,加密后的密文必须转换为16进制字符串表示。
注意:2019.01.01以后接入的商户默认“不填”
BF6DC5D23519
refundModeString(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


响应报文

参数类型(长度)必填描述示例
versionString(3)M接口版本号,固定为“2.0”2.0
charsetString(8)M参数编码,固定为“UTF-8”UTF-8
signStringM报文签名,使用商户支付密钥对rspData内的数据进行验签
signTypeStringM签名算法,固定为”SHA-256”SHA-256
rspData请求数据
rspCodeStringM处理结果,SUC0000:请求处理成功
其他:请求处理失败
SUC0000
rspMsgStringM详细信息,请求处理失败时返回错误描述
dateTimeString(14)M响应时间,银行返回该数据的时间
格式:yyyyMMddHHmmss
20160624121212
bankSerialNoString(20)M银行的退款流水号16280672300000000010
currencyString(2)M退款币种,固定为:“10”10
amountStringM退款金额,格式:xxxx.xx0.01
refundRefNoStringO银行的退款参考号608061000002
bankDateString(8)M退款受理日期
格式:yyyyMMdd
20160624
bankTimeString(6)M退款受理时间
格式:HHmmss
121201
refundSerialNoStringM商户上送流水号123456789
settleAmountStringM实际退款金额,格式:xxxx.xx0.01
discountAmountStringM退回优惠金额,格式:xxxx.xx0.01
以下字段联系招行配置控制参数后返回(默认不返回):
uniqueUserIDString(30)C支付用户ID,由身份证+姓名生成(推荐使用)UQwanCunLbp6cl1RbDFODrhLrAa48=
expandUserIDString(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退款失败具体失败原因参考报错信息