1.支付成功后的订单在半年时间内都是可以发起退款交易,当日发起的退款请求,是从当日正交易额度中扣除,当日如果没有正交易,是无法退款的。
2.退款成功后,也有异步回调,退款的异步回调地址,是正交易回调地址。
3.查询接口属于后台模式对接,商户后台技术人员可以发起http get/post请求,Content-Type设置为application/x-www-form-urlencoded,字符编码格式使用UTF-8
4.测试环境接口地址:https://dhjt-uat.chinaums.com/queryService/UmsWebPayPlugins
5.生产环境接口地址:https://生产域名/queryService/UmsWebPayPlugins
6.签名逻辑跟支付下单接口一样,如有不清楚的地方可以与大华捷通对接技术人员咨询
7.退款订单号refundOrderId也需遵循商户订单号生成规范,即以银商分配的4位来源编号作为账单号的前4位,且在商户系统中 此账单号保证唯一。总长度需大于6位,小于28位。银商的推荐规则为:{来源编号(4位)}{时间(yyyyMMddmmHHssSSS)(17位)}{7位随机数}
8.请求参数使用URLEncode进行URL编码后再进行传递,防止出现乱码问题
8.查询结果同步返回JSON格式的字符串,验证签名规则如下:
(1).将JSON字符串转成JSON对象,获取全部参数,处理sign参数外,其他参数参数值全部放入集合M(参数sign不要放入集合M中)
(2).遍历集合M,取出全部的参数key,将参数key字典序排列,根据排序后的参数key获取对应的value,将非空的参数key和参数value用"="拼接,多个参数之间用"&"拼接。
(3).最后再拼接签名秘钥,组成一个待前面的字符串A
(4).使用相应的签名算法,对字符串A进行签名,得到本地签名结果字符串B
(5).忽略大小写对比字符串B与sign参数值是否相等
参数名称 | 参数说明 | 参数类型 | 长度 | 是否必须 | 备注 |
---|---|---|---|---|---|
version | 版本号 | 字符串 | 10 | 是 | 固定值:20191031 |
msgType | 消息类型 | 字符串 | 10 | 是 | 固定值:refund |
msgId | 消息ID | 字符串 | 4 | 是 | 固定值:10UU |
requestTimestamp | 报文请求时间 | 字符串 | 19 | 是 | 格式yyyy-MM-dd HH:mm:ss |
merOrderId | 商户订单号 | 字符串 | 6..32 | 是 | 支付下单接口传入的支付订单号 |
mid | 商户号 | 字符串 | 15 | 是 | |
tid | 终端号 | 字符串 | 8 | 是 | |
billDate | 订单下单日期 | 字符串 | 10 | 是 | 格式:yyyy-MM-dd(鼠标单击查看说明) |
instMid | 业务类型 | 字符串 | 1..32 | 是 | 固定值:UACDEFAULT |
refundAmount | 退款金额 | 数字,单位:分 | 10 | 是 | 如果分分账交易,需要全部退款,此处传入支付总金额 |
refundOrderId | 退款订单号 | 字符串 | 6..28 | 是 | 跟merOrderId一样的生成规则 |
refundDesc | 退款描述 | 字符串 | 30 | 否 | 异步回调,原样返回 |
platformAmount | 平台退款金额 | 数字,单位:分 | 10 | 否 | 如果只退子商户金额,该参数填0 |
subOrders | 子商户退款明细 | JSONArray字符串 | 否 | 传参格式与正交易一致, 没有分账交易或者一次全额退款,不需要传递, 如果正交易是使用goods进行分账, 退款时使用subOrders退款, 需要传merOrderId(goods分账明细中的商户子订单号) |
|
subOrders | mid | 字符串 | 子商户号 | 否 | 没有分账交易或者一次全额退款,不需要传递 |
totalAmount | 数字 | 子商户号所得金额(分) | |||
merOrderId | 字符串 | 商户子订单号 | |||
refundOrderId | 字符串 | 商户退款子订单号 | |||
inAcctNo | 银联网 关交易 结算账 户号 | 字符串 | 64 | 否 | 银联网关退款交易时必传。与下
单接口中该字段相同。 经过 Base64编码。 |
acctType | 银联网 关交易 结算账 户类型 | 字符串 | 2 | 否 | 银联网关退款交易时必传。 银行个人账户: 1)个人银行借记账户:01 2)个人银行贷记账户:02 3)个人银行准贷记账户:03 4)银行预付费账户:05 支付账户: 1)个人支付账户:10 2)单位支付账户:11 银行对公账户: 1)对公银行账户:20 |
termType | 银联网 关交易 终端类 型 | 字符串 | 10 | 否 | 注意:银联网关交易时需要填
写。 电脑:PC 手机:PHONE 其他:OTHERS |
signType | 签名算法 | 字符串 | 10 | 否 | 支持SM3(推荐),SHA256,不传默认SM3 |
sign | 签名 | 字符串 | 64 | 是 | 签名规则(鼠标单击查看说明) |
参数名称 | 参数说明 | 参数类型 | 长度 | 是否必须 | 备注 |
---|---|---|---|---|---|
version | 版本号 | 字符串 | 10 | 是 | 固定值:20191031 |
errCode | 平台错误码 | 字符串 | 64 | 是 | 取值参考下面说明 |
errMsg | 版本号 | 字符串 | 255/td> | 是 | |
responseTimestamp | 报文响应时间 | 字符串 | 19 | 是 | 格式yyyy-MM-dd HH:mm:ss |
refundFunds | 退款渠道列表 | 字符串 | 30 | 否 | |
refundFundsDesc | 退款渠道描述 | 字符串 | 30 | 否 | |
refundInvoiceAmount | 实付部分退款金额 | 数字,单位:分 | 10 | 否 | |
refundOrderId | 退款订单号 | 字符串 | 30 | 否 | |
refundTargetOrderId | 目标系统退货订单号 | 字符串 | 30 | 否 | |
refundStatus | 退款状态 | 字符串 | 30 | 否 | 参考下面取值说明 |
refundAmount | 总退款金额 | 数字,单位:分 | 10 | 否 | |
seqId | 平台流水号,类似检索参考号 | 字符串 | 32 | 否 | |
settleRefId | 清分ID | 字符串 | 32 | 否 | 如果来源方传了bankRefId就等于bankRefId,否则等于seqId |
refId | 检索参考号 | 字符串 | 32 | 否 | |
status | 交易状态 | 字符串 | 32 | 否 | 查看下面说明 |
targetOrderId | 第三方订单号 | 字符串 | 100 | 否 | |
targetSys | 目标平台代码 | 字符串 | 100 | 否 | 查看下面说明 |
targetStatus | 目标平台的状态 | 字符串 | 100 | 否 | |
buyerId | 买家ID | 字符串 | 100 | 否 | |
targetMid | 支付渠道商户号 | 字符串 | 100 | 否 | 各渠道情况不同,酌情转换 |
bankCardNo | 银行卡号 | 字符串 | 100 | 否 | |
bankInfo | 银行信息 | 字符串 | 100 | 否 | |
billFunds | 支付渠道列表 | 字符串 | 100 | 否 | |
billFundsDesc | 支付渠道描述 | 字符串 | 100 | 否 | |
buyerPayAmount | 买家付款的金额 | 数字,单位:分 | 10 | 否 | 支付宝会有 |
buyerUsername | 买家用户名 | 字符串 | 100 | 否 | |
couponAmount | 网付计算的优惠金额 | 数字,单位:分 | 10 | 否 | |
invoiceAmount | 给用户开具发票的金额 | 数字,单位:分 | 10 | 否 | |
totalAmount | 订单金额 | 数字,单位:分 | 10 | 否 | |
payTime | 支付时间 | 字符串 | 19 | 否 | 格式yyyy-MM-dd HH:mm:ss |
receiptAmount | 商户实收金额 | 数字,单位:分 | 10 | 否 | 支付宝会有 |
settleDate | 结算日期 | 字符串 | 10 | 否 | 格式yyyy-MM-dd |
billDate | 订单下单日期 | 字符串 | 10 | 否 | 格式:yyyy-MM-dd |
queryId | 银联商务大华捷通系统流水号 | 字符串 | 30 | 是 | |
msgType | 消息类型 | 字符串 | 1..64 | 是 | 原样返回 |
merOrderId | 商户订单号 | 字符串 | 6..32 | 是 | 原样返回 |
mid | 商户号 | 字符串 | 15 | 是 | 原样返回 |
tid | 终端号 | 字符串 | 8 | 是 | 原样返回 |
employeeNo | 操作员工号 | 字符串 | 30 | 否 | 原样返回 |
attachedData | 商户附加数据 | 字符串 | 200 | 否 | 原样返回 |
originalAmount | 订单原始金额,单位分 | 数字 | 10 | 否 | 原样返回 |
totalAmount | 支付总金额,单位分 | 数字 | 10 | 是 | 原样返回 |
platformAmount | 平台商户分账金额 | 数字 | 10 | 否 | 原样返回 |
subOrders | 分账明细 | 字符串 | 10 | 否 | 原样返回 |
signType | 签名算法 | 字符串 | 10 | 是 | 原样返回 |
extend1 | 扩展字段1 | 字符串 | 50 | 否 | 原样返回 |
extend2 | 扩展字段2 | 字符串 | 50 | 否 | 原样返回 |
extend3 | 扩展字段3 | 字符串 | 50 | 否 | 原样返回 |
extend4 | 扩展字段4 | 字符串 | 50 | 否 | 原样返回 |
sign | 签名 | 字符串 | 64 | 是 | 签名规则(鼠标单击查看说明) |
注意:商户收到通知后,需要对通知做出响应:成功收到时响应”SUCCESS”;失败时响应”FAILED”。
针对重复收到通知的问题处理:
如果网付没有收到商户响应的SUCCESS字串,或者商户应答的报文中不包含SUCCESS字串,或者网络异常,系统会在24小时内尝试多次通知。商户收到重复通知时可以执行以下1或2进行处理:
1.商户主动调退款结果查询接口,以查询结果为准。
2.通知报文里面有商户订单号,商户可根据订单号、msgType=refund和订单状态判断是否是重复通知,并忽略已经处理了的订单的重复通知。
3.退款通知根据TransType区分,TransType=36为退款通知,TransType=33为支付通知
通知会以POST形式发出,包含参数如下,有些参数可能不会存在(出于安全考虑,实际通知报文含有个随机字段,key-value值不固定,且参与签名):
参数名称 | 参数说明 | 参数类型 | 长度 | 是否必须 | 备注 |
---|---|---|---|---|---|
version | 版本号 | 字符串 | 10 | 是 | 固定值:20191031 |
refundOrderId | 退款订单号 | 字符串 | 30 | 否 | |
responseTimestamp | 报文响应时间 | 字符串 | 19 | 是 | 格式yyyy-MM-dd HH:mm:ss |
refundAmount | 退款金额 | 数字,单位:分 | 10 | 是 | |
refundDesc | 退款说明 | 字符串 | 30 | 否 | |
refundTargetOrderId | 退款渠道订单号 | 字符串 | 50 | 否 | |
refundPayTime | 退款时间 | 字符串 | 19 | 否 | 格式yyyy-MM-dd HH:mm:ss |
refundSettleDate | 结算日期 | 字符串 | 10 | 否 | 格式yyyy-MM-dd |
seqId | 平台流水号,类似检索参考号 | 字符串 | 32 | 否 | |
settleRefId | 清分ID | 字符串 | 32 | 否 | 如果来源方传了bankRefId就等于bankRefId,否则等于seqId |
refId | 检索参考号 | 字符串 | 32 | 否 | |
status | 交易状态 | 字符串 | 32 | 否 | 查看下面说明 |
targetOrderId | 第三方订单号 | 字符串 | 100 | 否 | |
targetSys | 目标平台代码 | 字符串 | 100 | 否 | 查看下面说明 |
targetStatus | 目标平台的状态 | 字符串 | 100 | 否 | |
buyerId | 买家ID | 字符串 | 100 | 否 | |
targetMid | 支付渠道商户号 | 字符串 | 100 | 否 | 各渠道情况不同,酌情转换 |
bankCardNo | 银行卡号 | 字符串 | 100 | 否 | |
bankInfo | 银行信息 | 字符串 | 100 | 否 | |
billFunds | 支付渠道列表 | 字符串 | 100 | 否 | |
billFundsDesc | 支付渠道描述 | 字符串 | 100 | 否 | |
buyerPayAmount | 买家付款的金额 | 数字,单位:分 | 10 | 否 | 支付宝会有 |
buyerUsername | 买家用户名 | 字符串 | 100 | 否 | |
couponAmount | 网付计算的优惠金额 | 数字,单位:分 | 10 | 否 | |
invoiceAmount | 给用户开具发票的金额 | 数字,单位:分 | 10 | 否 | |
totalAmount | 订单金额 | 数字,单位:分 | 10 | 否 | |
payTime | 支付时间 | 字符串 | 19 | 否 | 格式yyyy-MM-dd HH:mm:ss |
receiptAmount | 商户实收金额 | 数字,单位:分 | 10 | 否 | 支付宝会有 |
settleDate | 结算日期 | 字符串 | 10 | 否 | 格式yyyy-MM-dd |
subBuyerId | 子买家ID,比如微信的subOpenId | 字符串 | 30 | 否 | |
billDate | 订单下单日期 | 字符串 | 10 | 否 | 格式:yyyy-MM-dd |
queryId | 银联商务大华捷通系统流水号 | 字符串 | 30 | 是 | |
msgType | 消息类型 | 字符串 | 1..64 | 是 | 原样返回 |
merOrderId | 商户订单号 | 字符串 | 6..32 | 是 | 原样返回 |
mid | 商户号 | 字符串 | 15 | 是 | 原样返回 |
tid | 终端号 | 字符串 | 8 | 是 | 原样返回 |
employeeNo | 操作员工号 | 字符串 | 30 | 否 | 原样返回 |
attachedData | 商户附加数据 | 字符串 | 200 | 否 | 原样返回 |
originalAmount | 订单原始金额,单位分 | 数字 | 10 | 否 | 原样返回 |
totalAmount | 支付总金额,单位分 | 数字 | 10 | 是 | 原样返回 |
platformAmount | 平台商户分账金额 | 数字 | 10 | 否 | 原样返回 |
subOrders | 分账明细 | 字符串 | 10 | 否 | 原样返回 |
signType | 签名算法 | 字符串 | 10 | 是 | 原样返回 |
extend1 | 扩展字段1 | 字符串 | 50 | 否 | 原样返回 |
extend2 | 扩展字段2 | 字符串 | 50 | 否 | 原样返回 |
extend3 | 扩展字段3 | 字符串 | 50 | 否 | 原样返回 |
extend4 | 扩展字段4 | 字符串 | 50 | 否 | 原样返回 |
sign | 签名 | 字符串 | 64 | 是 | 签名规则(鼠标单击查看说明) |
取值 | 描述 | 原因和应对措施 | 系统失败 |
---|---|---|---|
SUCCESS | 成功 | 无 | 无 |
INTERNAL_ERROR | 内部错误 | 系统错误,请联系技术支持 | 是 |
BAD_REQUEST | 请求报文有错 | 报文格式或字段值有误,请对照文档检查。 | 是 |
NO_SERVICE | 没有能处理请求msgtype的服务 | msgType错误,请检查文档,msgType是否拼写正确 | 是 |
POSITION_LACK | 头寸不足 | 头寸不足 | 是 |
TIMEOUT | 处理超时 | 处理超时,很可能是微信和支付宝的网络请求没应答,建议重试或者撤销交易 | 是 |
NO_ORDER | 找不到请求的原始订单 | 对应的mid+merOrderId不正确,无法找到原交易,请检查merOrderId是否跟原交易一致。 | 是 |
OPERATION_NOT_ALLOWED | 当前不允许此操作 | 订单已经关闭,不能执行退货等操作 | 是 |
TARGET_FAIL | 支付宝方支付失败,如请求没有成功,或者请求成功,但是没有正确处理。 | 支付宝或者微信方业务失败,请根据返回信息确定具体原因。 | 是 |
DUP_ORDER | 重复的订单请求 | 支付请求的merOrderId重复,请检查终端是否做过复位操作,导致流水号等重复。 | 是 |
NET_ERROR | 跟支付包通讯出问题,包括请求发送异常,报文应答不是200,请求被取消,应答超时等。 | 通讯问题,联系运行检查网络情况。 | 是 |
NO_MERCHANT | 找不到请求指定的商户 | 请求报文的mid在网付前置无法找到相关的配置,请确认终端的商户号是否正确在网付前置配置,是否经过转商户处理。 | 是 |
ORDER_PROCESSING | 订单正在处理中,不允许并发操作。 | 当前订单的上一次操作没有完成,订单处于锁定状态,请等待一分钟后再试。 | 是 |
INACTIVE_MERCHANT | 商户被置为inactive状态 | 交易商户在网付前置被冻结。 | 是 |
ABNORMAL_REQUEST_TIME | 请求时间异常 | 请求终端或者平台的系统时间不正常,请检查系统时间。 | 是 |
TXN_DISCARDED | 请求开始处理时间延迟过大,交易被丢弃。 | 系统负载过大,交易被丢弃,请联系运行。 | 是 |
BAD_SIGN | 签名错误 | 报文签名错误,请联系技术指导签名算法。 | 是 |
INVALID_MSGSRC | 商户来源错误 | 系统配置有问题,请联系技术。 | 是 |
INVALID_ORDER | 订单信息异常 | 该订单支付时有异常,缺少关键数据,请先做一笔订单查询,补充关键数据后再次进行退货等操作。 | 是 |
NO_CROSS_DAY_TRADING | 不允许跨日交易 | 可能某些渠道不支持跨日撤销,建议做退货。 | 是 |
DENIED_IP | 不允许此IP交易 | IP不在白名单中,请联系管理员确认。 | 是 |
INVLID_MERCHANT_CONFIG | 错误的商户配置 | 商户配置参数有问题,请联系业务人员检查商户配置参数。 | 是 |
INVALID_RESPONSE | 无效的应答报文 | 支付渠道方的应答报文有问题,比如验签失败、报文格式错误等。 | 是 |
取值 | 描述 | 备注 |
---|---|---|
Alipay 1.0 | 支付宝1.0协议 | 比较少用 |
Alipay 2.0 | 支付宝2.0协议 | 比较少用 |
WXPay | 微信 | |
YQB | 壹钱包 | |
QMF | 全民付远程快捷 | |
UnionPay | 银联钱包 | |
BaiDu | 百度钱包 | |
JD | 京东钱包 | |
SF | 顺丰顺手付 |
取值 | 描述 | 备注 |
---|---|---|
UNKNOWN | 不明确的交易状态 | 需要调退款查询接口确认退款结果 |
SUCCESS | 退款成功 | |
FAIL | 退款失败 | |
PROCESSING | 退款处理中 | 需要调退款查询接口确认退款结果 |