接口名称：统一收单交易退款接口
英文名称：alipay.trade.refund
主要用于交易资金的退款
一、文档地址
官方文档地址：[url]https://docs.open.alipay.com/api_1/alipay.trade.refund[/url]
二、开发前准备工作
调用步骤：[url]https://openclub.alipay.com/read.php?tid=12194&fid=69[/url]
注意事项：1、支持沙箱测试；2、需签约并添加功能；3、支持第三方调用。
如何签约以及签约无法成功等相关签约问题：[url]https://openclub.alipay.com/read.php?tid=276&fid=72[/url]
注：该接口为辅助接口，只要签约当面付、手机网站支付、电脑网站支付和APP支付，四个支付接口中其中一个就可以调用。
三、接口集成代码示例
1、参数说明
（1）out_trade_no：商户订单号，该参数值为支付接口中设置的out_trade_no参数值；
（2）trade_no：支付宝交易号，该参数值为支付接口订单创建后返回的trade_no参数值；
注：out_trade_no和trade_no至少必传其中一个参数，两者同时设置优先取值trade_no。
（3）out_request_no：标识一次退款请求，进行部分退款时必传，每一次请求设置都不一样；
2、JAVA版请求示例
public static void main(String[] args) throws AlipayApiException { AlipayClient alipayClient = new DefaultAlipayClient(AlipayConfig.gatewayUrl, AlipayConfig.app_id, AlipayConfig.merchant_private_key, AlipayConfig.format, AlipayConfig.charset, AlipayConfig.alipay_public_key, AlipayConfig.sign_type); AlipayTradeRefundRequest request = new AlipayTradeRefundRequest(); AlipayTradeRefundModel model = new AlipayTradeRefundModel(); //外部订单号，与tradeNo二选一 model.setOutTradeNo("sao201881610515614516"); // model.setTradeNo("2019031222001494890500825908"); //退款金额 model.setRefundAmount("3"); //OutTradeNo：标识一次退款请求，同一笔交易多次退款需要保证唯一，如需部分退款，则此参数必传。 model.setOutRequestNo("HZ01RF001"); request.setBizModel(model); AlipayTradeRefundResponse response = alipayClient.execute(request); if(response.isSuccess()){ System.out.println("调用成功"); } else { System.out.println("调用失败"); } System.out.println(response.getBody()); }
支付金额10元，部分退款3元返回的响应参数示例：
{"alipay_trade_refund_response":{"code":"10000","msg":"Success","buyer_logon_id":"uqq***@sandbox.com","buyer_user_id":"2088102175794899","fund_change":"Y","gmt_refund_pay":"2019-03-19 14:02:42","out_trade_no":"sao201881610515614516","refund_detail_item_list":[{"amount":"3.00","fund_channel":"ALIPAYACCOUNT"}],"refund_fee":"3.00","send_back_fee":"3.00","trade_no":"2019031922001494891000002604"},"sign":"dMDySpsb5WW6804uunIuweeNssnCcFyFzFrLZqN/l/7iRKJRnEq5C1sLyLAWKUAjwwgL2dm+f7792u2tRFAU9YaqyJwF/NxbG2yeXtxU9KoOAK/rit5HBLat8Ci6hdGeuImsyFFSq67Z8cP2Dvqyy4sr068Garj+vY0JL+Gvnrxe8aEttoxg+nms13MgSjx4Ybu+IB45XNIuCCZ9+oGp79y7Btrxpd/NcmGjYM/bpqX2P6QRLLSNBorG9WbOudw1F5V/vJbhH0FCzmjpKIhAl9pum4MygdwENSXUs5sntNRYF+krW0tuDwQpYC5bXSFFdJ63Xs39zqJVZPEjZ30ejw=="}
3、PHP版请求示例
<?php require_once 'AopSdk.php'; $aop = new AopClient (); $aop->appId = '填写您的appid'; $aop->rsaPrivateKey = '填写您的私钥'; $aop->alipayrsaPublicKey='填写您的支付宝公钥'; $aop->gatewayUrl = 'https://openapi.alipay.com/gateway.do'; $aop->apiVersion = '1.0'; $aop->signType = 'RSA2'; $aop->postCharset='utf-8'; $aop->format='json'; $date=date("YmdHis"); $arr=range(1000,9999); shuffle($arr); $request = new AlipayTradeRefundRequest (); $request->setBizContent("{" . ""out_trade_no":"sao201881610515614517"," . ""out_request_no":"HZ01RF001"," . ""refund_amount":3" . " }"); $result = $aop->execute($request); //第三方调用 //$result = $aop->execute($request,"","app_auth_token"); echo json_encode($result);
支付金额10元，部分退款3元返回的响应参数示例：
{"alipay_trade_refund_response":{"code":"10000","msg":"Success","buyer_logon_id":"uqq***@sandbox.com","buyer_user_id":"2088102175794899","fund_change":"Y","gmt_refund_pay":"2019-03-19 14:13:35","out_trade_no":"sao201881610515614517","refund_detail_item_list":[{"amount":"3.00","fund_channel":"ALIPAYACCOUNT"}],"refund_fee":"3.00","send_back_fee":"3.00","trade_no":"2019031922001494891000003623"},"sign":"kxCMOJ/vsnPb22r3dUae34eZyyPb/tNSkvwtNnRotpveXcKsd8O/ETo3CSH43Kztg5JYgAhCseqMBRFm7fTO/BarO2E9F7gpJA94ST5osP8PvLgZjmmq+bSOHvlGE5rYOrZ5NABAHm44JC1S97o82JrsSzGCq+5Bz+Wq5neXvGfmOkbKEBZyaT37N3W5MyypX2YBHifhPWODbkbtVxWtgvd8OamfuW+YQWk6dz+DtMRAuaXVFe9/M2c7KP1f4qVAxn/hLMvEPEwYdJ+0HxNPzH1EGh17lRdocA0W4RpnyL2h1q8wE53GR66fhPTRIYSyHORV5LAjPXyTpKcjmgaRdw=="}
4、.NET版请求示例
IAopClient client = new DefaultAopClient(config.gatewayUrl, config.app_id, config.private_key, "json", "1.0", "RSA2", config.alipay_public_key, config.charset, false); AlipayTradeRefundRequest request = new AlipayTradeRefundRequest(); request.BizContent="{" + ""out_trade_no":"20190321ygyg45447000001"," + // ""trade_no":"2019032222001481940568519359"," + ""refund_amount":0.03," + // ""out_request_no":"121217878121454"," + //部分退款必须要设置 ""refund_reason":"正常退款"" + "}"; AlipayTradeRefundResponse response = client.Execute(request); Console.WriteLine(response.Body);
全额退款返回的响应参数示例：
{"alipay_trade_refund_response":{"code":"10000","msg":"Success","buyer_logon_id":"171******56","buyer_user_id":"2088022304381942","fund_change":"Y","gmt_refund_pay":"2019-03-22 17:53:23","out_trade_no":"20190321ygyg45447000001","refund_detail_item_list":[{"amount":"0.03","fund_channel":"PCREDIT"}],"refund_fee":"0.03","send_back_fee":"0.03","trade_no":"2019032222001481940568519359"},"sign":"TiG5+duw4cPJYCLIcdANc2tm031whwgavieIgM1iV+PMDXbREhINf/apQE+VV+QVKNJGMfjgldTV4g/fOHhn0FYujFB0GxwVluj0K1J8AnYiZoBgUdncVUkmmepu4Nx1c+yf9UWiFZMQf4hYiY33MFpRhe8R/FWGymcPdPXGFc0GnXBOShzTBOskxPK9EZaMWlBjZbEI3mo+R1k55xJosVutPFG3LL8jKff4zeGHmOGQF1OdwpszTX5gTPWnsWnUCMFxdDz3yLaPiM7Ki8Ha3FWBWh/2S65TvrQ41zqso6KNUQE9kU2UW+tZHP0cXo4JFox1oPVuuS5Y52PAol7AQg=="}
四、注意事项
1、退款要求
必须在退款的有效期内退款内：交易状态必须是trade_success。
默认支付成功后，退款有效期为3个月（90天）。
2、如何判断交易是否退款成功
（1）根据退款接口返回响应参数fund_change（本次退款是否发生了资金变化），参数值为Y，资金发生变化，退款成功；
（2）可通过退款查询接口判断，返回具体详细的退款参数值表示退款成功。
具体可参考如何判断是否退款成功：[url]https://openclub.alipay.com/read.php?tid=8328&fid=72[/url]
3、退款资金是到哪个账户
调用退款接口，资金是原路返回的，使用什么支付渠道支付，即退款到哪个支付渠道。
4、如何判断交易是否到账
调用退款接口成功，是立即退款的，但具体到账时间以账户收到资金为准，如退款到银行账户，以银行账户的结算时间为准，无法查询具体到账时间。
5、退款是否触发异步通知
统一收单退款接口暂时不支持设置异步地址参数来接收异步通知，但在发生退款的时候，会触发的异步通知是发送到该交易支付接口设置的notify_url地址中。
（1）部分退款都会触发异步通知；
（2）全额退款，交易状态变为交易关闭（TRADE_CLOSED），具体是否会触发异步通知根据该交易支付接口中的通知触发条件判断。
具体可参考异步信息判断交易：[url]https://openclub.alipay.com/read.php?tid=8328&fid=72&page=1#anchor2[/url]
6、如何判断是退款的异步通知
相较支付成功的异步通知，退款的异步通知参数中一定会返回out_biz_no（商户业务号）、refund_fee（总退款金额）等参数。
7、如何判断是哪笔的退款异步通知
根据商户业务号（out_biz_no）区分：
（1）全额退款：退款请求时若设置out_request_no参数值，返回out_request_no参数值；
若未设置，返回请求时设置的out_trade_no参数值。
（2）部分退款：退款请求时设置的out_request_no参数值。
如果还是报错，请按如下方式进行提问：
正确提问方式：使用环境（沙箱还是正式环境）+接口名称（中文+英文）+ 请求参数 + 报错信息详情
