alipay.trade.refund(统一收单交易退款接口)

转载 https://blog.csdn.net/a369405354/article/details/79385819

当交易发生之后一段时间内，由于买家或者卖家的原因需要退款时，卖家可以通过退款接口将支付款退还给买家，支付宝将在收到退款请求并且验证成功之后，按照退款规则将支付款按原路退到买家帐号上。 交易超过约定时间（签约时设置的可退款时间）的订单无法进行退款 支付宝退款支持单笔交易分多次退款，多次退款需要提交原支付订单的商户订单号和设置不同的退款单号。一笔退款失败后重新提交，要采用原来的退款单号。总退款金额不能超过用户实际支付金额

公共参数

请求地址

环境	HTTPS请求地址
正式环境	https://openapi.alipay.com/gateway.do

公共请求参数

参数	类型	是否必填	最大长度	描述	示例值
app_id	String	是	32	支付宝分配给开发者的应用ID	2014072300007148
method	String	是	128	接口名称	alipay.trade.refund
format	String	否	40	仅支持JSON	JSON
charset	String	是	10	请求使用的编码格式，如utf-8,gbk,gb2312等	utf-8
sign_type	String	是	10	商户生成签名字符串所使用的签名算法类型，目前支持RSA2和RSA，推荐使用RSA2	RSA2
sign	String	是	344	商户请求参数的签名串，详见签名	详见示例
timestamp	String	是	19	发送请求的时间，格式"yyyy-MM-dd HH:mm:ss"	2014-07-24 03:07:50
version	String	是	3	调用的接口版本，固定为：1.0	1.0
app_auth_token	String	否	40	详见应用授权概述
biz_content	String	是		请求参数的集合，最大长度不限，除公共参数外所有请求参数都必须放在这个参数中传递，具体参照各产品快速接入文档

请求参数

参数	类型	是否必填	最大长度	描述	示例值
out_trade_no	String	特殊可选	64	订单支付时传入的商户订单号,不能和 trade_no同时为空。	20150320010101001
trade_no	String	特殊可选	64	支付宝交易号，和商户订单号不能同时为空	2014112611001004680073956707
refund_amount	Price	必选	9	需要退款的金额，该金额不能大于订单金额,单位为元，支持两位小数	200.12
refund_reason	String	可选	256	退款的原因说明	正常退款
out_request_no	String	可选	64	标识一次退款请求，同一笔交易多次退款需要保证唯一，如需部分退款，则此参数必传。	HZ01RF001
operator_id	String	可选	30	商户的操作员编号	OP001
store_id	String	可选	32	商户的门店编号	NJ_S_001
terminal_id	String	可选	32	商户的终端编号	NJ_T_001
goods_detail	GoodsDetail[]	可选		退款包含的商品列表信息，Json格式。  其它说明详见：“商品明细说明”

公共响应参数

参数	类型	是否必填	最大长度	描述	示例值
code	String	是	-	网关返回码,详见文档	40004
msg	String	是	-	网关返回码描述,详见文档	Business Failed
sub_code	String	否	-	业务返回码，参见具体的API接口文档	ACQ.TRADE_HAS_SUCCESS
sub_msg	String	否	-	业务返回码描述，参见具体的API接口文档	交易已被支付
sign	String	是	-	签名,详见文档	DZXh8eeTuAHoYE3w1J+POiPhfDxOYBfUNn1lkeT/V7P4zJdyojWEa6IZs6Hz0yDW5Cp/viufUb5I0/V5WENS3OYR8zRedqo6D+fUTdLHdc+EFyCkiQhBxIzgngPdPdfp1PIS7BdhhzrsZHbRqb7o4k3Dxc+AAnFauu4V6Zdwczo=

响应参数

参数	类型	是否必填	最大长度	描述	示例值
trade_no	String	必填	64	2013112011001004330000121536	支付宝交易号
out_trade_no	String	必填	64	商户订单号	6823789339978248
buyer_logon_id	String	必填	100	用户的登录id	159****5620
fund_change	String	必填	1	本次退款是否发生了资金变化	Y
refund_fee	Price	必填	11	退款总金额	88.88
gmt_refund_pay	Date	必填	32	退款支付时间	2014-11-27 15:45:57
refund_detail_item_list	TradeFundBill	选填		退款使用的资金渠道
store_name	String	选填	512	交易在支付时候的门店名称	望湘园联洋店
buyer_user_id	String	必填	28	买家在支付宝的用户id	2088101117955611
present_refund_buyer_amount	String	选填	11	本次退款金额中买家退款金额	88.88
present_refund_discount_amount	String	选填	11	本次退款金额中平台优惠退款金额	88.88
present_refund_mdiscount_amount	String	选填	11	本次退款金额中商家优惠退款金额	88.88

请求示例

• JAVA 
• .NET 
• PHP 
• HTTP请求源码

1. $aop = new AopClient ();

2. $aop->gatewayUrl = 'https://openapi.alipay.com/gateway.do';

3. $aop->appId = 'your app_id';

4. $aop->rsaPrivateKey = '请填写开发者私钥去头去尾去回车，一行字符串';

5. $aop->alipayrsaPublicKey='请填写支付宝公钥，一行字符串';

6. $aop->apiVersion = '1.0';

7. $aop->signType = 'RSA2';

8. $aop->postCharset='GBK';

9. $aop->format='json';

10. $request = new AlipayTradeRefundRequest ();

11. $request->setBizContent("{" .

12. "\"out_trade_no\":\"20150320010101001\"," .

13. "\"trade_no\":\"2014112611001004680073956707\"," .

14. "\"refund_amount\":200.12," .

15. "\"refund_currency\":\"USD\"," .

16. "\"refund_reason\":\"正常退款\"," .

17. "\"out_request_no\":\"HZ01RF001\"," .

18. "\"operator_id\":\"OP001\"," .

19. "\"store_id\":\"NJ_S_001\"," .

20. "\"terminal_id\":\"NJ_T_001\"," .

21. " \"goods_detail\":[{" .

22. " \"goods_id\":\"apple-01\"," .

23. "\"alipay_goods_id\":\"20010001\"," .

24. "\"goods_name\":\"ipad\"," .

25. "\"quantity\":1," .

26. "\"price\":2000," .

27. "\"goods_category\":\"34543238\"," .

28. "\"body\":\"特价手机\"," .

29. "\"show_url\":\"http://www.alipay.com/xxx.jpg\"" .

30. " }]" .

31. " }");

32. $result = $aop->execute ( $request);

33.  

34. $responseNode = str_replace(".", "_", $request->getApiMethodName()) . "_response";

35. $resultCode = $result->$responseNode->code;

36. if(!empty($resultCode)&&$resultCode == 10000){

37. echo "成功";

38. } else {

39. echo "失败";

40. }

响应示例

• JSON 示例 
• XML 示例

1. {

2. "alipay_trade_refund_response": {

3. "code": "10000",

4. "msg": "Success",

5. "trade_no": "支付宝交易号",

6. "out_trade_no": "6823789339978248",

7. "buyer_logon_id": "159****5620",

8. "fund_change": "Y",

9. "refund_fee": 88.88,

10. "gmt_refund_pay": "2014-11-27 15:45:57",

11. "refund_detail_item_list": [

12. {

13. "fund_channel": "ALIPAYACCOUNT",

14. "bank_code": "CEB",

15. "amount": 10,

16. "real_amount": 11.21,

17. "fund_type": "DEBIT_CARD"

18. }

19. ],

20. "store_name": "望湘园联洋店",

21. "buyer_user_id": "2088101117955611",

22. "present_refund_buyer_amount": "88.88",

23. "present_refund_discount_amount": "88.88",

24. "present_refund_mdiscount_amount": "88.88"

25. },

26. "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"

27. }

异常示例

• JSON 示例

1. {

2. "alipay_trade_refund_response": {

3. "code": "20000",

4. "msg": "Service Currently Unavailable",

5. "sub_code": "isp.unknow-error",

6. "sub_msg": "系统繁忙"

7. },

8. "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"

9. }

业务错误码

公共错误码

错误码	错误描述	解决方案
ACQ.SYSTEM_ERROR	系统错误	请使用相同的参数再次调用
ACQ.INVALID_PARAMETER	参数无效	请求参数有错，重新检查请求后，再调用退款
ACQ.SELLER_BALANCE_NOT_ENOUGH	卖家余额不足	商户支付宝账户充值后重新发起退款即可
ACQ.REFUND_AMT_NOT_EQUAL_TOTAL	退款金额超限	检查退款金额是否正确，重新修改请求后，重新发起退款
ACQ.REASON_TRADE_BEEN_FREEZEN	请求退款的交易被冻结	联系支付宝小二，确认该笔交易的具体情况
ACQ.TRADE_NOT_EXIST	交易不存在	检查请求中的交易号和商户订单号是否正确，确认后重新发起
ACQ.TRADE_HAS_FINISHED	交易已完结	该交易已完结，不允许进行退款，确认请求的退款的交易信息是否正确
ACQ.TRADE_STATUS_ERROR	交易状态非法	查询交易，确认交易是否已经付款
ACQ.DISCORDANT_REPEAT_REQUEST	不一致的请求	检查该退款号是否已退过款或更换退款号重新发起请求
ACQ.REASON_TRADE_REFUND_FEE_ERR	退款金额无效	检查退款请求的金额是否正确
ACQ.TRADE_NOT_ALLOW_REFUND	当前交易不允许退款	检查当前交易的状态是否为交易成功状态以及签约的退款属性是否允许退款，确认后，重新发起请求