开发文档

申请退款

应用场景:

当交易发生之后一段时间内,由于买家或者卖家的原因需要退款时,卖家可以通过退款接口将支付款退还给买家,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)

子商户号或商户识别码

19000001099000000101

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)

子商户号或商户识别码

19000001099000000101

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

appidmch_id不匹配

appidmch_id不匹配

请确认appidmch_id是否匹配

REQUIRE_POST_METHOD

请使用post方法

未使用post传递参数

请检查请求参数是否通过post方法提交

SIGNERROR

签名错误

参数签名结果不正确

请检查签名参数和方法是否都符合签名算法要求

XML_FORMAT_ERROR

XML格式错误

XML格式错误

请检查XML参数格式是否正确

INVALID_CERTIFICATE

证书错误

客户端证书无效或未使用证书

检查是否客户端是否使用正确有效证书来请求,下载证书:参见商户证书