申请退款
应用场景:
当交易发生之后一段时间内,由于买家或者卖家的原因需要退款时,卖家可以通过退款接口将支付款退还给买家,QQ钱包将在收到退款请求并且验证成功之后,按照退款规则将支付款按原路退到买家帐号上。
注意:
1.交易时间超过一年的订单无法提交退款;
2.QQ钱包退款支持单笔交易分多次退款,多次退款需要提交原支付订单的商户订单号和设置不同的退款单号。一笔退款失败后重新提交,要采用原来的退款单号。总退款金额不能超过用户实际支付金额。
3.退款将先退优惠单,再退用户单。eg:订单10元,用户支付9元,优惠1元。 若请求退款1元,则只会退优惠单,用户单将不退款。
接口地址:
https://api.qpay.qq.com/cgi-bin/pay/qpay_refund.cgi
是否需要证书:
是。获取证书:参见商户证书。
操作员账户:
接口需要用到的操作员账户密码,可以由以下两种方式任意一种方式获得:
1. 商户号id和登陆密码是一组操作员账户和密码。
2. 创建操作员。详情参见:https://kf.qq.com/faq/170112AZ7Fzm170112VNz6zE.html
接口规则
· 为保证交易安全性,采用HTTPS传输
· 采用POST方法提交
· 统一采用UTF-8字符编码
更多详情见接口规则
请求参数:
变量名 | 字段名 | 字段类型 | 必须 | 备注 | 示例 |
appid | 应用ID | String(32) | 否 | 腾讯开放平台或QQ互联平台审核通过的应用APPID | 1007033799 |
sub_appid | 子商户应用ID | String(32) | 否 | 腾讯开放平台或QQ互联平台审核通过的应用APPID | 1007033790 |
mch_id | 商户号 | String(32) | 是 | QQ钱包分配的商户号 | 1900000109 |
sub_mch_id | 子商户号 | String(32) | 是 | 子商户号或商户识别码 | 1900000109或9000000101 |
nonce_str | 随机字符串 | String(32) | 是 | 随机字符串,不长于32位 | 3e5a036cb4bc3a677a38ad9d69eb3feb |
sign | 商户签名算法规则 | String(128) | 是 | 商户签名,详见商户签名算法规则 | 5K8264ILTKCH16CQ2502SI8ZNMTM67VS |
transaction_id | QQ钱包订单号 | String(32) | 二选一 | QQ钱包订单号,优先使用。请求30天或更久之前支付的订单时,此参数不能为空。 | 1353933301461607211903715555 |
out_trade_no | 商户订单号 | String(32) | 二选一 | 商户系统内部的订单号,32个字符内、可包含字母,说明见商户订单号 当没提供transaction_id时需要传入该参数 | 20150806125346 |
out_refund_no | 商户退款单号 | String(32) | 是 | 商户系统内部的退款单号,商户系统内部唯一,同一退款单号多次请求只退一笔 | 2015080612 |
refund_fee | 退款申请金额 | Int | 是 | 本次退款申请的退回金额。单位:分。币种:人民币 | 100 |
op_user_id | 操作员ID | String(32) | 是 | 操作员帐号, 默认为商户号,参见本页说明:操作员账户 | 1900000109 |
op_user_passwd | 操作员密码的MD5 | String(32) | 是 | 操作员密码的MD5 | e47fefadd66e024bb2b85dfeb5fe86ba |
refund_account | 退款资金来源 | String(30) | 否 | REFUND_SOURCE_UNSETTLED_FUNDS---未结算资金退款(默认使用未结算资金退款) REFUND_SOURCE_RECHARGE_FUNDS---可用现金账户资金退款 | REFUND_SOURCE_RECHARGE_FUNDS |
示例如下:
<xml>
<op_user_id>1267727601</op_user_id>
<op_user_passwd>20A8587EE8FE76C02495344769D73729</op_user_passwd>
<out_refund_no>2016072208586049</out_refund_no>
<nonce_str>058b7db104cc37ac4ae59928b12fb092</nonce_str>
<out_trade_no>2016072208586047</out_trade_no>
<mch_id>1301278501</mch_id>
<refund_fee>1300</refund_fee>
<sign>3E6136FBBE0BBAD3482C9966434AEA74</sign>
<xml>
返回结果:
变量名 | 字段名 | 类型 | 必填 | 描述 | 示例 |
return_code | 返回状态码 | String(16) | 是 | SUCCESS/FAIL | SUCCESS |
return_msg | 返回信息 | String(128) | 否 | 返回信息,如非空,为错误原因 | 签名失败 |
retcode | 手Q CGI原始错误码 | String(16) | 是 | 原始错误码 | 10025 |
retmsg | 手Q CGI原始错误信息 | String(128) | 否 | 原始错误信息 | 系统繁忙 |
下列字段,在return_code为成功时有返回:
变量名 | 字段名 | 类型 | 必填 | 描述 | 示例 |
appid | 应用ID | String(32) | 否 | 腾讯开放平台或QQ互联平台审核通过的应用APPID | 1007033799 |
sub_appid | 子商户应用ID | String(32) | 否 | 腾讯开放平台或QQ互联平台审核通过的应用APPID | 1007033790 |
mch_id | 商户号 | String(32) | 是 | QQ钱包分配的商户号 | 1900000109 |
sub_mch_id | 子商户号 | String(32) | 是 | 子商户号或商户识别码 | 1900000109或9000000101 |
sign | 商户签名算法规则 | String(128) | 是 | 商户签名,详见商户签名算法规则 | 5K8264ILTKCH16CQ2502SI8ZNMTM67VS |
result_code | 业务结果 | String(32) | 是 | SUCCESS/FAIL | SUCCESS |
err_code | 错误代码 | String(32) | 否 | 详情见错误代码 | SYSTEMERROR |
err_code_des | 错误代码描述 | String(128) | 否 | 错误返回的信息描述 | 系统繁忙 |
nonce_str | 随机字符串 | String(32) | 是 | 随机字符串,不长于32位 | 3e5a036cb4bc3a677a38ad9d69eb3feb |
下列字段,在result_code为成功时有返回:
变量名 | 字段名 | 类型 | 必填 | 描述 | 示例 |
transaction_id | QQ钱包订单号 | String(32) | 是 | QQ钱包订单号。 | 1353933301461607211903715555 |
out_trade_no | 商户订单号 | String(32) | 是 | 商户系统内部的订单号,32个字符内、可包含字母。其它说明见商户订单号 | 20150806125346 |
total_fee | 订单金额 | Int | 是 | 商户订单总金额,单位为分,只能为整数,详见订单金额 | 888 |
out_refund_no | 商户退款单号 | String(32) | 是 | 商户系统内部的退款单号,商户系统内部唯一,同一退款单号多次请求只退一笔 | 2015080612 |
refund_id | QQ钱包退款单号 | String(32) | 是 | QQ钱包退款单号,在成功受理商户的退款申请后,QQ钱包会为本次退款申请生成该 QQ钱包退款单号 | 1121218133801201611098791376 |
refund_channel | 退款方式 | String(16) | 是 | ORIGINAL 原路退回 BALANCE 退款到余额 | ORIGINAL |
refund_fee | 退款申请金额 | Int | 是 | 本次退款申请的退回金额。单位:分。币种:人民币 | 666 |
示例如下:
<xml>
<retcode><![CDATA[0]]></retcode>
<retmsg><![CDATA[ok]]></retmsg>
<mch_id><![CDATA[1301278501]]></mch_id>
<nonce_str><![CDATA[775bfd4126b2eb8e2e70dda568e3fa31]]></nonce_str>
<result_code><![CDATA[SUCCESS]]></result_code>
<return_code><![CDATA[SUCCESS]]></return_code>
<return_msg><![CDATA[SUCCESS]]></return_msg>
<sign><![CDATA[B46441AB8FFBE83CCCDAD614D24BC30B]]></sign>
<transaction_id>1267727601461607221803678319</transaction_id>
<out_trade_no>2016072208586047</out_trade_no>
<out_refund_no>2016072208586049</out_refund_no>
<total_fee>1300</total_fee>
<refund_id>1121267727601607220535066841</refund_id>
<refund_fee>1300</refund_fee>
<refund_channel>ORIGINAL</refund_channel>
</xml>
错误码:
错误码 | 描述 | 原因 | 解决办法 |
SYSTEMERROR | 系统错误 | 系统错误 | 请用相同参数再次调用API |
USER_ACCOUNT_ABNORMAL | 退款请求失败 | 用户帐号注销 | 此状态代表退款申请失败,商户可自行处理退款。 |
NOTENOUGH | 余额不足 | 商户可用退款余额不足 | 此状态代表退款申请失败,商户可根据具体的错误提示做相应的处理。 |
INVALID_TRANSACTIONID | 无效transaction_id | 请求参数未按指引进行填写 | 请求参数错误,检查原交易号是否存在或发起支付交易接口返回失败 |
PARAM_ERROR | 参数错误 | 请求参数未按指引进行填写 | 请求参数错误,请重新检查再调用退款申请 |
APPID_NOT_EXIST | APPID不存在 | 参数中缺少APPID | 请检查APPID是否正确 |
MCHID_NOT_EXIST | MCHID不存在 | 参数中缺少MCHID | 请检查MCHID是否正确 |
APPID_MCHID_NOT_MATCH | appid和mch_id不匹配 | appid和mch_id不匹配 | 请确认appid和mch_id是否匹配 |
REQUIRE_POST_METHOD | 请使用post方法 | 未使用post传递参数 | 请检查请求参数是否通过post方法提交 |
SIGNERROR | 签名错误 | 参数签名结果不正确 | 请检查签名参数和方法是否都符合签名算法要求 |
XML_FORMAT_ERROR | XML格式错误 | XML格式错误 | 请检查XML参数格式是否正确 |
INVALID_CERTIFICATE | 证书错误 | 客户端证书无效或未使用证书 | 检查是否客户端是否使用正确有效证书来请求,下载证书:参见商户证书 |