完成 接入准备 后，商家/服务商可根据本文指引快速接入 支付宝预授权。

说明：支付宝预授权 暂不支持沙箱调试。

信用预授权场景

当用户使用如租车、充电桩、酒店预订等服务时，在冻结用户资金前先由芝麻信用对其进行信用评估，信用好则不用冻结资金，通过信用的奖惩来规范用户行为，提升解冻转支付的成功率。具体可查看芝麻免押产品接入指南。

资金预授权场景

当用户使用如租车、充电桩、酒店预订等服务时，用户需要先做一笔资金授权。当服务完成，扣款时，商家再调 alipay.trade.pay（统一收单交易支付接口）从授权资金中扣除消费金额，剩余金额返还给用户。冻结资金需要商户根据自身业务做出合理预估，支持一次授权多次扣款，累计扣款最多不能超过冻结金额。

资金预授权完整时序图

第一步：生成资金冻结订单

开发者可调用 alipay.fund.auth.order.app.freeze （线上资金授权冻结接口）生成资金冻结订单并获取参数串用于小程序端/商家 APP 唤起收银台完成冻结。

示例代码

完整的 JSON 数据可复制+请求

package com.java.sdk.demo;

import com.alipay.v3.ApiClient;
import com.alipay.v3.ApiException;
import com.alipay.v3.ApiResponse;
import com.alipay.v3.Configuration;
import com.alipay.v3.util.GenericExecuteApi;
import com.alipay.v3.util.model.AlipayConfig;
import com.alipay.v3.util.model.CustomizedParams;
import com.alipay.v3.util.model.OpenApiGenericRequest;
import java.io.File;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class GenericExecute {

    public static void main(String[] args) throws ApiException {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        // 初始化alipay参数（全局设置一次）
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey("<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->");
        alipayConfig.setAlipayPublicKey("<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->");
        defaultClient.setAlipayConfig(alipayConfig);
        GenericExecuteApi api = new GenericExecuteApi();
        Map<String, Object> bizParams = new HashMap<>();
        Map<String, Object> bizContent = new HashMap<>();
        bizContent.put("extra_param", "{\"category\":\"CHARGE_PILE_CAR\",\"serviceId\":\"2020042800000000000001450466\"}");
        bizContent.put("business_params", "{\"outRiskInfo\":\"{\"mcCreateTradeTime\":\"2022-03-11 12:46:09\",\"extraAccountCertnoLastSix\":\"000011\",\"mobileOperatingPlatform\":\"ios\",\"sysVersion\":\"15.4.2\",\"mcCreateTradeIp\":\"11.110.111.43\"}\"}");
        bizContent.put("identity_params", "{\"identity_hash\":\"acc2b92ffc5ed9b472faa19748f10045c30434132784f774b00216a56b8841c6\"}");
        List<Map<String, Object>> postPayments = new ArrayList<>();
        Map<String, Object> postPayments0 = new HashMap<>();
        postPayments0.put("amount", "0.01");
        postPayments0.put("description", "2元/小时，99元封顶");
        postPayments0.put("name", "租金");
        postPayments.add(postPayments0);
        bizContent.put("post_payments", postPayments);
        bizContent.put("payee_logon_id", "159****5620");
        bizContent.put("product_code", "PRE_AUTH_ONLINE");
        bizContent.put("order_title", "XX租车押金");
        bizContent.put("disable_pay_channels", "[{\"payChannelType\":\"OPTIMIZED_MOTO\"},{\"payChannelType\":\"BIGAMOUNT_CREDIT_CARTOON\"}]");
        bizContent.put("out_order_no", "8077735255938023");
        bizContent.put("out_request_no", "8077735255938032");
        bizContent.put("enable_pay_channels", "[{\"payChannelType\":\"PCREDIT_PAY\"},{\"payChannelType\":\"MONEY_FUND\"}]");
        bizContent.put("amount", "0.01");
        bizContent.put("deposit_product_mode", "POSTPAY");
        bizContent.put("timeout_express", "2d");
        bizContent.put("payee_user_id", "2088102000275795");
        bizParams.put("biz_content", bizContent);
        try {
            String response = api.sdkExecute("alipay.fund.auth.order.app.freeze", bizParams);
            System.out.println(response);
        } catch (ApiException e) {
            System.out.println("调用失败");
        }
    }
}

重要入参说明

参数名称	参数说明
out_order_no	商户授权资金订单号
out_request_no	商户本次资金操作的请求流水号
order_title	订单标题
amount	需要冻结的金额，由商户根据自身业务评估金额
product_code	产品码，固定为 PRE_AUTH_ONLINE
notify_url	异步通知地址，异步通知响应详情可查看文中授权异步通知章节，当用户授权成功时将触发异步通知返回 auth_no等授权结果信息。若未设置 notify_url 则需调用 alipay.fund.auth.operation.detail.query（资金授权操作查询接口）轮询用户授权结果，当接口返回 order_status = AUTHORIZED 时则用户授权成功
payee_user_id	可选字段，收款账户的支付宝用户号
payee_logon_id	可选字段，收款账户的支付宝登录号（email或手机号）如果商户希望用户能够使用花呗，则用户号(payee_user_id)和登录号(payee_logon_id)两者必须传入其一
enable_pay_channels	可选字段，可以指定支付渠道，如果不传，默认为签约协议的支付渠道；若需要限制支付渠道，目前仅支持余额宝（MONEY_FUND）、花呗（PCREDIT_PAY）以及芝麻信用（CREDITZHIMA）。冻结用户花呗（PCREDIT_PAY）额度渠道升级中，暂不支持新用户申请接入，请关注后续通知

注意：请严格按照接口文档中的参数入参，传入非接口文档中的参数是无效的，并且可能会导致请求被拦截或其它异常。

第二步：唤起冻结页

说明：

请将支付宝客户端升级至最新版本。

若唤起支付宝收银台报错参数异常，请关注支付宝返回给客户端的具体错误信息。

APP 支付唤起冻结

Android 样例代码

final  String orderInfo = orderStr;//orderStr从第一步：生成资金冻结订单，从服务端获取
Runnable payRunnable =  new  Runnable() {
     @Override
  public   void   run ()   {
        PayTask alipay =  new  PayTask(DemoActivity. this );
   Map<String,String> result = alipay.payV2(orderInfo, true );
   Message msg =  new  Message();
   msg.what = SDK_PAY_FLAG;
   msg.obj = result;
   mHandler.sendMessage(msg);
    }
};  
// 必须异步调用 
Thread payThread =  new  Thread(payRunnable);
payThread.start();

入参说明

PayTask 对象主要为商家提供订单支付、查询功能，及获取当前开发包版本号。

获取 PayTask 支付对象调用支付（支付行为需要在独立的非 ui 线程中执行）。

出参获取

示例代码

private  Handler mHandler =  new  Handler() {
  public   void   handleMessage (Message msg)   {
  Result result =  new  Result((String) msg.obj);
  Toast.makeText(DemoActivity. this , result.getResult(),
     Toast.LENGTH_LONG).show();
};
};

IOS 样例代码

可查看 iOS集成方案。

H5 支付唤起冻结

开发者可通过 ap.tradePay 接口，传入支付宝订单字符串唤起支付，用户确认后即可冻结资金。

注意：该组件仅支持支付宝端内 H5 访问唤起，不支持端外 H5 访问。

示例代码

<script src= "https://gw.alipayobjects.com/as/g/h5-lib/alipayjsapi/3.1.1/alipayjsapi.inc.min.js"></script> 
<button id = "J_btn" class = "btn btn-default">支付</button>
<script>
  var btn = document.querySelector('#J_btn');
  btn.addEventListener('click', function(){
    ap.tradePay({
       orderStr : 'timestamp=2016-12-27...'//orderStr从第一步：生成资金冻结订单，从服务端获取
    }, function( res ) {
      ap.alert(res.resultCode);
    });
  });
</script>

使用介绍

可直接传入一个字符串作为 OPTION.orderStr 参数。

OPTION 参数说明

名称	类型	必填	描述
tradeNO	String	否	交易号，多个交易号请用英文分号 ; 分隔。
partnerID	String	否	商户 id。
bizType	String	否	交易类型，默认为 `trade`。
bizSubType	String	否	交易子类型。
bizContext	String	否	支付额外的参数，格式为 JSON 字符串。
orderStr	String	否	完整的支付参数拼接成的字符串，从服务端获取。

CALLBACK 参数说明

名称	类型	描述
resultCode	String	支付结果状态码，详情可查看下表。

resultCode 支付状态码说明：

resultCode	描述
9000	订单支付成功。
8000	正在处理中。
4000	订单支付失败。
6001	用户中途取消。
6002	网络连接出错。
99	用户点击忘记密码导致快捷界面退出（only iOS）。

小程序支付唤起冻结

开发者通过在小程序内调用 my.tradePay 接口，唤起预授权冻结流程（入参即接入流程中获取的 orderStr）。

注意：开发者需通过真机调试的方式调试该接口的功能，若用 IDE 调试该接口则会报无效的 API 入参。

示例代码

my.tradePay({
  orderStr: 'orderStr', //orderStr从第一步：生成资金冻结订单，从服务端获取
  success: (res) => {
    my.alert({
      content: JSON.stringify(res),
    });
  },
  fail: (res) => {
    my.alert({
      content: JSON.stringify(res),
    });
  }
});

唤起冻结注意事项

status=INIT，表示用户授权中，可调用 alipay.fund.auth.operation.detail.query（资金授权操作查询接口）每隔 5 秒钟查询一次授权冻结的状态，如依然是用户授权中，则再等待5秒钟继续使用查询接口查询，直至 1 分钟后超时（推荐每隔 5 秒查询一次，共进行 12 次查询，具体根据商家业务情况决定）。

如超时前最后一次查询依然返回用户授权中，则马上调用 alipay.fund.auth.operation.cancel（资金授权撤销接口）将该笔预授权冻结交易撤销。

如接口返回系统异常，先通过查询接口查询授权冻结的状态，并根据查询结果进行后续操作。

返回错误码为 SYSTEM_ERROR 时，请调用查询接口确定授权状态，并根据状态确定下一步操作。

授权异步通知

当用户使用服务会在支付宝客户端唤起冻结页用户同意协议，输入密码之后会收到授权签约异步通知，平台通过 alipay.fund.auth.order.app.freeze（线上资金授权冻结接口）传入的 notify_url 主动以 POST 的方式推送给商户。

用户授权成功异步通知样例

https://www.merchant.com/receive_notify.htm?notify_type=trade_status_sync&notify_id=91722adff935e8cfa58b3aabf4dead6ibe&notify_time=2017-02-16 21:46:15&sign_type=RSA2&sign=WcO+t3D8Kg71dTlKwN7r9PzUOXeaBJwp8/FOuSxcuSkXsoVYxBpsAidprySCjHCjmaglNcjoKJQLJ28/Asl93joTW39FX6i07lXhnbPknezAlwmvPdnQuI01HZsZF9V1i6ggZjBiAd5lG8bZtTxZOJ87ub2i9GuJ3Nr/NUc9VeY=&auth_no=2014070800002001550000014417&out_order_no=4977164666634053&operation_id=2014070800032850551&out_request_no=8077735255938032&operation_type=FREEZE&amount=0.01&status=SUCCESS&gmt_create=2014-09-15 11:23:04&gmt_trans=2014-09-15 11:23:04&payer_logon_id=test***@alitest.com&payer_user_id=2088102000275885&payee_logon_id=159****5620&payee_user_id=2088102000275795&total_freeze_amount=0.01&total_unfreeze_amount=0.01&total_pay_amount=0.01&rest_amount=0.01&credit_amount=0.01&fund_amount=0.01&total_freeze_credit_amount=0.01&total_freeze_fund_amount=0.01&total_unfreeze_credit_amount=0.01&total_unfreeze_fund_amount=0.01&total_pay_credit_amount=0.01&total_pay_fund_amount=0.01&rest_credit_amount=0.01&rest_fund_amount=0.01&pre_auth_type=CREDIT_AUTH&trans_currency=USD

参数说明

参数名	参数说明
auth_no	支付宝资金授权订单号
out_order_no	商家的资金授权订单号
operation_id	支付宝的资金操作流水号
out_request_no	商家资金操作流水号

异步通知参数说明具体请参考异步参数说明。

验签方法

同步接口和异步通知验签，可查看验签流程。

异步通知接收代码规范

接收程序执行完后必须打印输出 success。如果商家反馈给支付宝的字符不是 success 这7个字符，服务器会不断重发通知，直到超过 24 小时 22 分钟。

一般情况下，25 小时以内完成 8 次通知（通知的间隔频率一般是 4m、10m、10m、1h、2h、6h、15h）；接收程序执行完成后，该页面不能执行页面跳转。如果执行页面跳转，支付宝会接收不到 success 字符，会被支付宝服务器判定为该页面程序运行出现异常，而重发处理结果通知。

示例代码

第三步：资金冻结转支付场景

当商家获得用户授权完成线上资金冻结场景操作后，如果业务场景需要用户进行支付，而并不只是冻结押金，则需要调用 alipay.trade.pay（统一收单交易支付接口）完成扣款操作。

注意：

商家在进行冻结转支付时，若扣款金额大于冻结的押金，会出现扣款失败，在第一步资金冻结时需要商户根据自身业务合理评估出冻结金额。

冻结转支付使用 alipay.trade.pay（统一收单交易支付接口）为通用接口，在资金授权场景下：

授权码的参数为 auth_no 而非当面付中的 auth_code；授权码也没有 25-30 开头的限制。

资金授权过程无需传入scene 参数。

示例代码

package com.java.sdk.demo;

import com.alipay.v3.ApiException;
import com.alipay.v3.ApiClient;
import com.alipay.v3.util.model.AlipayConfig;
import com.alipay.v3.Configuration;
import com.alipay.v3.api.AlipayTradeApi;
import com.alipay.v3.model.*;
import java.io.File;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class AlipayTradeApiPay {

    public static void main(String[] args) throws ApiException {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        // 初始化alipay参数（全局设置一次）
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey("<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->");
        alipayConfig.setAlipayPublicKey("<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->");
        defaultClient.setAlipayConfig(alipayConfig);
        AlipayTradeApi api = new AlipayTradeApi();
        AlipayTradePayModel data = new AlipayTradePayModel();
        data.setAuthConfirmMode("COMPLETE");
        ExtendParams extendParams = new ExtendParams();
        extendParams.setSysServiceProviderId("2088511833207846");
        extendParams.setSpecifiedSellerName("XXX的跨境小铺");
        extendParams.setCardType("S0JP0000");
        data.setExtendParams(extendParams);
        List<GoodsDetail> goodsDetail = new ArrayList<GoodsDetail>();
        GoodsDetail goodsDetail0 = new GoodsDetail();
        goodsDetail0.setQuantity(1);
        goodsDetail0.setPrice("2000");
        goodsDetail0.setGoodsCategory("34543238");
        goodsDetail0.setCategoriesTree("124868003|126232002|126252004");
        goodsDetail0.setGoodsId("apple-01");
        goodsDetail0.setShowUrl("http://www.alipay.com/xxx.jpg");
        goodsDetail0.setGoodsName("ipad");
        goodsDetail.add(goodsDetail0);
        data.setGoodsDetail(goodsDetail);
        data.setTerminalId("NJ_T_001");
        List<String> queryOptions = new ArrayList<String>();
        queryOptions.add("voucher_detail_list");
        data.setQueryOptions(queryOptions);
        PromoParam promoParams = new PromoParam();
        promoParams.setActualOrderTime("2018-09-25 22:47:33");
        data.setPromoParams(promoParams);
        data.setOutTradeNo("20150320010101001");
        data.setProductCode("PRE_AUTH_ONLINE");
        data.setSubject("XX租车租金");
        data.setAuthNo("2016110310002001760201905725");
        data.setTotalAmount("88.88");
        data.setStoreId("NJ_001");
        try {
            AlipayTradePayResponseModel response = api.pay(data);
        } catch (ApiException e) {
            AlipayTradePayDefaultResponse errorObject = (AlipayTradePayDefaultResponse) e.getErrorObject();
            System.out.println("调用失败:" + errorObject);
        }
    }
}

重要入参说明

参数名称	参数说明
notify_url	非必填，支付成功异步接收地址
auth_confirm_mode	非必填，预授权确认模式当 auth_confirm_mode = COMPLETE 时无需调用解冻接口，支付宝端在扣款成功后会自动解冻剩余金额，同时该笔授权订单完成。当 auth_confirm_mode = NOT_COMPLETE 时，商家收到支付成功通知后需要自行调用 alipay.fund.auth.order.unfreeze（资金授权解冻接口）将余额进行解冻。如果需要从一笔授权中完成多笔订单支付，保持 auth_no 不变，不同订单根据 out_trade_no 进行标识，此时 auth_confirm_mode 不传或者传入 NOT_COMPLETE；进行到最后一笔转支付时，auth_confirm_mode 传入 COMPLETE 由支付宝完成剩余金额自动解冻，或者商家自行调用解冻接口将剩余金额解冻。

参数名称

参数说明

notify_url

非必填，支付成功异步接收地址

auth_confirm_mode

非必填，预授权确认模式当 auth_confirm_mode = COMPLETE 时无需调用解冻接口，支付宝端在扣款成功后会自动解冻剩余金额，同时该笔授权订单完成。当 auth_confirm_mode = NOT_COMPLETE 时，商家收到支付成功通知后需要自行调用 alipay.fund.auth.order.unfreeze（资金授权解冻接口）将余额进行解冻。如果需要从一笔授权中完成多笔订单支付，保持 auth_no 不变，不同订单根据 out_trade_no 进行标识，此时 auth_confirm_mode 不传或者传入 NOT_COMPLETE；进行到最后一笔转支付时，auth_confirm_mode 传入 COMPLETE 由支付宝完成剩余金额自动解冻，或者商家自行调用解冻接口将剩余金额解冻。

注意：请严格按照接口文档中的参数入参，传入非接口文档中的参数是无效的，并且可能会导致请求被拦截或其它异常。

出参处理

response 中的 code=10000，表示接口调用成功，支付状态以异步通知或交易查询为准。

如果未收到异步通知，可以通过交易查询接口查询最新交易状态，如果返回 trade_status = WAIT_BUYER_PAY，商家可以调用预授权转支付重新发起扣款（注意：商户订单号 out_trade_no 保持不变）。

支付异步通知

资金授权转支付通知示例

gmt_create=2022-10-27 17:41:57&charset=utf-8&seller_email=$$$&subject=资金转支付&sign=$$$&buyer_id=2088********2180&invoice_amount=0.01&notify_id=202210270122****************555922&fund_bill_list=[{"amount":"0.01","fundChannel":"ALIPAYACCOUNT"}]&notify_type=trade_status_sync&trade_status=TRADE_SUCCESS&receipt_amount=0.01&app_id=2014********3222&buyer_pay_amount=0.01&sign_type=RSA2&seller_id=2088********0335&gmt_payment=2022-10-27 17:41:57&notify_time=2022-10-27 17:41:58&version=1.0&out_trade_no=202210278880110111pay&total_amount=0.01&trade_no=20221027****************4504&auth_app_id=2014********3222&buyer_logon_id=156****8305&point_amount=0.00

参数说明：

参数名称	参数说明
out_trade_no	商户外部交易号
trade_no	支付宝交易号
trade_status	交易状态
receipt_amount	实收金额

查看更多参数说明请参考当面付异步通知。

补充业务场景

除了主要业务接口外，支付宝预授权还提供了如授权解冻、撤销等接口帮助商家完善业务拼图。

资金授权解冻

当资金授权发生之后一段时间内，由于买家或者商家等其它原因需要要解冻资金，商家可通过 alipay.fund.auth.order.unfreeze（资金授权解冻接口）将授权资金进行解冻，支付宝将在收到解冻请求并验证成功后，按解冻规则将冻结资金按原路进行解冻并返回。

示例代码

完整的 JSON 数据可复制+请求：

package com.java.sdk.demo;

import com.alipay.v3.ApiException;
import com.alipay.v3.ApiClient;
import com.alipay.v3.util.model.AlipayConfig;
import com.alipay.v3.Configuration;
import com.alipay.v3.api.AlipayFundAuthOrderApi;
import com.alipay.v3.model.*;
import java.io.File;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class AlipayFundAuthOrderApiUnfreeze {

    public static void main(String[] args) throws ApiException {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        // 初始化alipay参数（全局设置一次）
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey("<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->");
        alipayConfig.setAlipayPublicKey("<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->");
        defaultClient.setAlipayConfig(alipayConfig);
        AlipayFundAuthOrderApi api = new AlipayFundAuthOrderApi();
        AlipayFundAuthOrderUnfreezeModel data = new AlipayFundAuthOrderUnfreezeModel();
        data.setOutRequestNo("2016101200104001110081001");
        data.setRemark("2014-05期解冻200.00元");
        data.setExtraParam("{\"unfreezeBizInfo\": \"{\"bizComplete\":\"true\"}\"}");
        data.setAmount("20.11");
        data.setAuthNo("2016101210002001810258115912");
        try {
            AlipayFundAuthOrderUnfreezeResponseModel response = api.unfreeze(data);
        } catch (ApiException e) {
            AlipayFundAuthOrderUnfreezeDefaultResponse errorObject = (AlipayFundAuthOrderUnfreezeDefaultResponse) e.getErrorObject();
            System.out.println("调用失败:" + errorObject);
        }
    }
}

说明：

支持全额解冻和部分解冻。

当业务流程为商家冻结用户资金并且在用户完成业务后直接转为支付场景时该接口非必须调用，可查看资金冻结转支付场景。解冻转支付时：

若 auth_confirm_mode = complete，无需调用解冻接口，支付宝端在扣款成功后会自动解冻剩余金额。

若 auth_confirm_mode = not_complete，在收到支付成功通知后，商家需自行调用解冻接口将余额进行解冻。

资金授权解冻通知示例

notify_url?gmt_create=2022-10-20 11%3A45%3A09&charset=utf-8&rest_amount=0.00&amount=0.01&notify_time=2022-10-20 11%3A45%3A10&operation_type=UNFREEZE&sign=$$$&out_order_no=20221020v1223102110&version=1.0&auth_no=202210201000************3940&notify_id=202210200022211***********5729313&notify_type=fund_auth_unfreeze&total_pay_amount=0.00&total_freeze_amount=0.01&gmt_trans=2022-10-20 11%3A45%3A09&auth_app_id=201410******3222&operation_id=2022102086******1805&total_unfreeze_amount=0.01&out_request_no=20221020134646013unfree03&payer_user_id=2088********2180&app_id=201410******3222&sign_type=RSA2&status=SUCCESS&payer_logon_id=156****8305

参数说明

参数名	参数说明
operation_type	资金操作类型，UNFREEZE：解冻
auth_no	支付宝资金授权订单号
out_request_no	商家资金操作流水号

其他参数可查看异步通知参数说明。

资金授权操作查询

商家可以通过资金授权操作查询接口 alipay.fund.auth.operation.detail.query（资金授权操作查询接口）查询单笔明细的详细信息，细分到每一次操作，如冻结、解冻。

示例代码

package com.java.sdk.demo;

import com.alipay.v3.ApiException;
import com.alipay.v3.ApiClient;
import com.alipay.v3.util.model.AlipayConfig;
import com.alipay.v3.Configuration;
import com.alipay.v3.api.AlipayFundAuthOperationDetailApi;
import com.alipay.v3.model.*;
import java.io.File;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class AlipayFundAuthOperationDetailApiQuery {

    public static void main(String[] args) throws ApiException {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        // 初始化alipay参数（全局设置一次）
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey("<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->");
        alipayConfig.setAlipayPublicKey("<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->");
        defaultClient.setAlipayConfig(alipayConfig);
        AlipayFundAuthOperationDetailApi api = new AlipayFundAuthOperationDetailApi();
        AlipayFundAuthOperationDetailQueryModel data = new AlipayFundAuthOperationDetailQueryModel();
        data.setOutOrderNo("8077735255938023");
        data.setOperationType("FREEZE");
        data.setOutRequestNo("20140216001001");
        data.setOperationId("20140216010020006400");
        data.setAuthNo("2014021601002000640012345678");
        try {
            AlipayFundAuthOperationDetailQueryResponseModel response = api.query(data);
        } catch (ApiException e) {
            AlipayFundAuthOperationDetailQueryDefaultResponse errorObject = (AlipayFundAuthOperationDetailQueryDefaultResponse) e.getErrorObject();
            System.out.println("调用失败:" + errorObject);
        }
    }
}

响应示例

{
    "gmt_create":"2014-01-01 20:00:00",
    "order_title":"0元购土豪金",
    "rest_credit_amount":0.01,
    "operation_type":"UNFREEZE",
    "remark":"2014-05期解冻200.00元",
    "credit_merchant_ext":"{\"1003190\":\"true\"}",
    "rest_fund_amount":0.01,
    "auth_no":"2014031600002001260000001000",
    "total_freeze_credit_amount":0.01,
    "order_status":"AUTHORIZED",
    "trans_currency":"USD",
    "gmt_trans":"2014-01-01 20:00:00",
    "operation_id":"20140216355864862002",
    "total_pay_fund_amount":0.01,
    "payer_user_id":"2088402019148643",
    "out_request_no":"20140216001001",
    "rest_amount":4600.00,
    "amount":200.00,
    "fund_amount":0.01,
    "total_pay_credit_amount":0.01,
    "pre_auth_type":"CREDIT_AUTH",
    "credit_amount":0.01,
    "out_order_no":"20140216001",
    "total_freeze_fund_amount":0.01,
    "total_pay_amount":0.00,
    "total_freeze_amount":4800.00,
    "extra_param":"{\"merchantExt\":\"key1=value1,key2=value2\"}",
    "payer_logon_id":"ali*@alipay.com",
    "status":"SUCCESS"
}

出参处理：

response 中的 status=SUCCESS 表示预授权成功；INIT：初始状态，表示已创建授权单，等待用户密码确认；CLOSED：关闭状态，超时未授权，支付宝将授权单关闭后的状态。

资金授权撤销

商家通过 alipay.fund.auth.operation.cancel（资金授权撤销接口）撤销用户资金授权。

注意：只有商家由于业务系统处理超时需要终止后续业务处理或者授权结果未知时可调用撤销，其它正常授权冻结的操作如需实现相同功能请调用资金授权解冻服务。提交资金授权后调用资金授权操作查询，没有明确的授权结果再调用支付宝预授权撤销。

示例代码

package com.java.sdk.demo;

import com.alipay.v3.ApiException;
import com.alipay.v3.ApiClient;
import com.alipay.v3.util.model.AlipayConfig;
import com.alipay.v3.Configuration;
import com.alipay.v3.api.AlipayFundAuthOperationApi;
import com.alipay.v3.model.*;
import java.io.File;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class AlipayFundAuthOperationApiCancel {

    public static void main(String[] args) throws ApiException {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        // 初始化alipay参数（全局设置一次）
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey("<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->");
        alipayConfig.setAlipayPublicKey("<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->");
        defaultClient.setAlipayConfig(alipayConfig);
        AlipayFundAuthOperationApi api = new AlipayFundAuthOperationApi();
        AlipayFundAuthOperationCancelModel data = new AlipayFundAuthOperationCancelModel();
        data.setOutOrderNo("4977164666634053");
        data.setOutRequestNo("2016100810000003551");
        data.setRemark("授权撤销");
        data.setOperationId("20161012405744018102");
        data.setAuthNo("2014070800002001550000014417");
        try {
            AlipayFundAuthOperationCancelResponseModel response = api.cancel(data);
        } catch (ApiException e) {
            AlipayFundAuthOperationCancelDefaultResponse errorObject = (AlipayFundAuthOperationCancelDefaultResponse) e.getErrorObject();
            System.out.println("调用失败:" + errorObject);
        }
    }
}

交易查询

商家通过 alipay.trade.query（统一收单线下交易查询接口）查询单笔明细的详细信息。

示例代码

package com.java.sdk.demo;

import com.alipay.v3.ApiException;
import com.alipay.v3.ApiClient;
import com.alipay.v3.util.model.AlipayConfig;
import com.alipay.v3.Configuration;
import com.alipay.v3.api.AlipayTradeApi;
import com.alipay.v3.model.*;
import java.io.File;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class AlipayTradeApiQuery {

    public static void main(String[] args) throws ApiException {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        // 初始化alipay参数（全局设置一次）
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey("<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->");
        alipayConfig.setAlipayPublicKey("<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->");
        defaultClient.setAlipayConfig(alipayConfig);
        AlipayTradeApi api = new AlipayTradeApi();
        AlipayTradeQueryModel data = new AlipayTradeQueryModel();
        List<String> queryOptions = new ArrayList<String>();
        queryOptions.add("trade_settle_info");
        data.setQueryOptions(queryOptions);
        data.setOutTradeNo("20150320010101001");
        data.setTradeNo("2014112611001004680 073956707");
        data.setOrgPid("2088101117952222");
        try {
            AlipayTradeQueryResponseModel response = api.query(data);
        } catch (ApiException e) {
            AlipayTradeQueryDefaultResponse errorObject = (AlipayTradeQueryDefaultResponse) e.getErrorObject();
            System.out.println("调用失败:" + errorObject);
        }
    }
}

重要入参说明

注意：请严格按照接口文档中的参数入参，传入非接口文档中的参数是无效的，并且可能会导致请求被拦截或其它异常。

outTradeNo：为授权转支付时传入的 outTradeNo。

出参处理

如果查询返回处理中 trade_ status = WAIT_BUYER_PAY 或 ORDER SUCCESS PAY INPROGRESS，商家可以调用预授权转支付重新发起扣款，需注意商户订单号 out_trade_no 保持不变。

交易退款

当交易发生之后一段时间内，由于买家或者卖家的原因需要退款时，卖家可以通过 alipay.trade.refund（统一收单交易退款接口）将支付款退还给买家，支付宝将在收到退款请求并且验证成功之后，按照退款规则将支付款按原路退到买家账号上。

注意：交易超过约定时间（签约时设置的可退款时间）的订单无法进行退款。支付宝退款支持单笔交易分多次退款，多次退款需要提交原支付订单的商户订单号和设置不同的退款单号。一笔退款失败后重新提交，要采用原来的退款单号。总退款金额不能超过用户实际支付金额。

示例代码

package com.java.sdk.demo;

import com.alipay.v3.ApiException;
import com.alipay.v3.ApiClient;
import com.alipay.v3.util.model.AlipayConfig;
import com.alipay.v3.Configuration;
import com.alipay.v3.api.AlipayTradeApi;
import com.alipay.v3.model.*;
import java.io.File;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class AlipayTradeApiRefund {

    public static void main(String[] args) throws ApiException {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        // 初始化alipay参数（全局设置一次）
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey("<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->");
        alipayConfig.setAlipayPublicKey("<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->");
        defaultClient.setAlipayConfig(alipayConfig);
        AlipayTradeApi api = new AlipayTradeApi();
        AlipayTradeRefundModel data = new AlipayTradeRefundModel();
        List<OpenApiRoyaltyDetailInfoPojo> refundRoyaltyParameters = new ArrayList<OpenApiRoyaltyDetailInfoPojo>();
        OpenApiRoyaltyDetailInfoPojo refundRoyaltyParameters0 = new OpenApiRoyaltyDetailInfoPojo();
        refundRoyaltyParameters0.setTransInType("userId");
        refundRoyaltyParameters0.setRoyaltyScene("达人佣金");
        refundRoyaltyParameters0.setAmount("0.1");
        refundRoyaltyParameters0.setTransOut("2088101126765726");
        refundRoyaltyParameters0.setRoyaltyType("transfer");
        refundRoyaltyParameters0.setTransIn("2088101126708402");
        refundRoyaltyParameters0.setDesc("分账给2088101126708402");
        refundRoyaltyParameters0.setTransInName("张三");
        refundRoyaltyParameters0.setTransOutType("userId");
        refundRoyaltyParameters.add(refundRoyaltyParameters0);
        data.setRefundRoyaltyParameters(refundRoyaltyParameters);
        data.setOutRequestNo("HZ01RF001");
        List<String> queryOptions = new ArrayList<String>();
        queryOptions.add("refund_detail_item_list");
        data.setQueryOptions(queryOptions);
        data.setOutTradeNo("20150320010101001");
        List<RefundGoodsDetail> refundGoodsDetail = new ArrayList<RefundGoodsDetail>();
        RefundGoodsDetail refundGoodsDetail0 = new RefundGoodsDetail();
        refundGoodsDetail0.setGoodsId("apple-01");
        refundGoodsDetail0.setOutItemId("outItem_01");
        refundGoodsDetail0.setOutSkuId("outSku_01");
        refundGoodsDetail0.setRefundAmount("19.50");
        refundGoodsDetail.add(refundGoodsDetail0);
        data.setRefundGoodsDetail(refundGoodsDetail);
        data.setTradeNo("2014112611001004680073956707");
        data.setRefundAmount("200.12");
        data.setRefundReason("正常退款");
        try {
            AlipayTradeRefundResponseModel response = api.refund(data);
        } catch (ApiException e) {
            AlipayTradeRefundDefaultResponse errorObject = (AlipayTradeRefundDefaultResponse) e.getErrorObject();
            System.out.println("调用失败:" + errorObject);
        }
    }
}

查询对账单下载地址

商家通过 alipay.data.dataservice.bill.downloadurl.query（查询对账单下载地址接口）获取商家离线账单下载地址。

示例代码

package com.java.sdk.demo;

import com.alipay.v3.ApiException;
import com.alipay.v3.ApiClient;
import com.alipay.v3.util.model.AlipayConfig;
import com.alipay.v3.Configuration;
import com.alipay.v3.api.AlipayDataDataserviceBillDownloadurlApi;
import com.alipay.v3.model.*;
import java.io.File;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class AlipayDataDataserviceBillDownloadurlApiQuery {

    public static void main(String[] args) throws ApiException {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        // 初始化alipay参数（全局设置一次）
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey("<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->");
        alipayConfig.setAlipayPublicKey("<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->");
        defaultClient.setAlipayConfig(alipayConfig);
        AlipayDataDataserviceBillDownloadurlApi api = new AlipayDataDataserviceBillDownloadurlApi();
        String billType = "trade";
        String billDate = "2016-04-05";
        String smid = "2088123412341234";
        try {
            AlipayDataDataserviceBillDownloadurlQueryResponseModel response = api.query(billType, billDate, smid);
        } catch (ApiException e) {
            AlipayDataDataserviceBillDownloadurlQueryDefaultResponse errorObject = (AlipayDataDataserviceBillDownloadurlQueryDefaultResponse) e.getErrorObject();
            System.out.println("调用失败:" + errorObject);
        }
    }
}

响应示例

{
    "bill_download_url":"http://dwbillcenter.alipay.com/downloadBillFile.resource?bizType=X&pid=X&fileType=X&bizDates=X&downloadFileName=X&fileId=X",
    "bill_file_code":"EMPTY_DATA_WITH_BILL_FILE"
}

重要出参说明

参数名称	参数说明
billDownloadUrl	对账单下载地址，下载地址有效时间为 30 秒，请尽快下载。

业务接口报错

关于业务接口报错请查看常见问题。

支付宝预授权快速接入

信用预授权场景#

资金预授权场景#

资金预授权完整时序图#

第一步：生成资金冻结订单#

示例代码#

重要入参说明#

第二步：唤起冻结页#

APP 支付唤起冻结#

Android 样例代码#

入参说明#

出参获取#

IOS 样例代码#

H5 支付唤起冻结#

示例代码#

使用介绍#

小程序支付唤起冻结#

示例代码#

唤起冻结注意事项#

授权异步通知#

用户授权成功异步通知样例#

参数说明#

验签方法#

异步通知接收代码规范#

示例代码#

第三步：资金冻结转支付场景#

示例代码#

重要入参说明#

出参处理#

支付异步通知#

资金授权转支付通知示例#

参数说明：#

补充业务场景#

资金授权解冻#

示例代码#

资金授权解冻通知示例#

参数说明#

资金授权操作查询#

示例代码#

响应示例#

出参处理：#

资金授权撤销#

示例代码#

交易查询#

示例代码#

重要入参说明#

出参处理#

交易退款#

示例代码#

查询对账单下载地址#

示例代码#

响应示例#

重要出参说明#

业务接口报错#

信用预授权场景

资金预授权场景

资金预授权完整时序图

第一步：生成资金冻结订单

示例代码

重要入参说明

第二步：唤起冻结页

APP 支付唤起冻结

Android 样例代码

入参说明

出参获取

IOS 样例代码

H5 支付唤起冻结

示例代码

使用介绍

小程序支付唤起冻结

示例代码

唤起冻结注意事项

授权异步通知

用户授权成功异步通知样例

参数说明

验签方法

异步通知接收代码规范

示例代码

第三步：资金冻结转支付场景

示例代码

重要入参说明

出参处理

支付异步通知

资金授权转支付通知示例

参数说明：

补充业务场景

资金授权解冻

示例代码

资金授权解冻通知示例

参数说明

资金授权操作查询

示例代码

响应示例

出参处理：

资金授权撤销

示例代码

交易查询

示例代码

重要入参说明

出参处理

交易退款

示例代码

查询对账单下载地址

示例代码

响应示例

重要出参说明

业务接口报错