完成接入准备后，商家/服务商可根据本文指引快速接入预授权支付。<br />**说明**：

- 预授权支付仅支持自研商家/服务商通过 [自研应用](https://ideservice.alipay.com/cms/site/02bijh) 或 [第三方应用](https://ideservice.alipay.com/cms/site/02bijh) 代调用方式，调用 API 接入。
- **预授权支付** 支持沙箱调试。
<a name="kMUIz"></a>
# 支付流程
用户使用服务（如：租车、充电桩、酒店预订）时，需先做一笔资金冻结授权，当服务完成后，进行扣款时，商家再从冻结资金中扣除消费金额，剩余金额解冻返还给用户。
```
sequenceDiagram
    actor 用户
    participant 支付宝客户端
    participant 商户系统
    participant 支付宝服务端

    rect rgb(200, 220, 240)
        Note over 用户,支付宝服务端: 冻结资金

        rect rgb(220, 235, 250)
            Note left of 用户: 商家扫用户付款码
            用户->>支付宝客户端: 1: 打开"支付宝"，选择付款
            支付宝客户端->>商户系统: 1.1: 通过扫码设备输入付款码
            商户系统->>支付宝服务端: 1.1.1: 调用alipay.fund.auth.order.freeze发起资金授权冻结操作
            支付宝服务端->>支付宝服务端: 1.1.1.1: 判断是否免密支付
            支付宝服务端-->>商户系统: 1.1.2: 返回授权成功的同步结果
            支付宝服务端-->>支付宝客户端: 2: 返回授权成功结果页和发送支付宝消息
        end

        商户系统->>支付宝服务端: 3: 调用alipay.fund.auth.operation.detail.query查询资金操作状态
        支付宝服务端-->>商户系统: 3.1: 同步返回查询结果<br/>冻结成功判断标准：status="SUCCESS"
        alt 结果未知
        商户系统->>支付宝服务端: 4: 调用alipay.fund.auth.operation.cancel撤销该笔冻结操作
        支付宝服务端-->>商户系统: 4.1: 同步返回撤销结果
				end

        rect rgb(220, 235, 250)
            Note left of 用户: 用户扫商家二维码
            商户系统->>支付宝服务端: 1: 调用alipay.fund.auth.order.voucher.create生成订单码
            支付宝服务端-->>商户系统: 1.1: 返回订单码
            商户系统-->>用户: 1.2: 展示订单码给用户
            用户->>支付宝客户端: 2: 扫描商户的订单码
            支付宝客户端->>支付宝服务端: 2.1: 输入密码，提交支付宝进行资金授权
            支付宝服务端-->>支付宝客户端: 2.2: 返回授权成功结果页和发送支付宝消息
        end

        商户系统->>支付宝服务端: 3: 调用alipay.fund.auth.operation.detail.query查询资金操作状态
        支付宝服务端-->>商户系统: 3.1: 同步返回查询结果<br/>冻结成功判断标准：status="SUCCESS"
        alt 结果未知
        商户系统->>支付宝服务端: 4: 调用alipay.fund.auth.operation.cancel撤销该笔冻结操作
        支付宝服务端-->>商户系统: 4.1: 同步返回撤销结果
				end
    end

    rect rgb(220, 240, 200)
        Note over 用户,支付宝服务端: 冻结资金转支付
        Note left of 用户: 如果业务场景需要用户支付，<br/>服务结束后商户主动调支付接口
        用户->>商户系统: 3: 服务结束
        商户系统->>支付宝服务端: 3.1: 调用alipay.trade.pay创建交易单并冻结资金支付给卖家
        支付宝服务端-->>商户系统: 3.2: 返回请求结果

        alt 获取扣款结果
            Note right of 商户系统: 收到异步通知
            支付宝服务端-->>商户系统: 4: 主动推送扣款信息到notify_url
            商户系统->>支付宝服务端: 4.1: 返回字符串 success
        else 未收到异步通知
            商户系统->>支付宝服务端: 5: 调用 alipay.trade.query，同步查询交易订单信息
            支付宝服务端-->>商户系统: 5.1: 同步返回交易信息
        end
    end

    rect rgb(240, 220, 200)
        Note over 用户,支付宝服务端: 解冻资金
        Note left of 用户: 如果业务场景不需要用户支付，<br/>服务结束后商户主动调解冻接口
        用户->>商户系统: 6: 服务结束
        商户系统->>支付宝服务端: 6.1: 调用alipay.fund.auth.order.unfreeze发起资金授权解冻
        支付宝服务端-->>商户系统: 6.2: 返回资金解冻结果
    end
```
<a name="iEvQP"></a>
## 冻结资金
**注意：**冻结资金需要商家根据自身业务做出合理预估，支持一次授权多次扣款，累计扣款最多不能超过冻结金额。
<a name="hYrV0"></a>
### 商家扫用户付款码
商家使用条码识别设备（如：扫码枪）扫描用户支付宝客户端上的条码，调用 [alipay.fund.auth.order.freeze](https://ideservice.alipay.com/cms/site/0iziyh)（资金授权冻结接口） 完成用户资金冻结授权，冻结资金要大于未来消费转支付金额，目前接口不支持追加冻结。根据是否需要输入密码可分为：免密模式和验密模式。
<a name="NjKMk"></a>
#### 免密模式
```
 sequenceDiagram
    actor 用户
    participant 支付宝客户端
    participant 商户系统
    participant 支付宝服务端

    用户->>支付宝客户端: 1: 打开"支付宝"，选择付款
    activate 支付宝客户端
    支付宝客户端->>商户系统: 1.1: 通过扫码设备输入付款码
    activate 商户系统
    商户系统->>支付宝服务端: 1.1.1: 调用alipay.fund.auth.order.freeze发起资金授权冻结操作
    activate 支付宝服务端
    支付宝服务端-->>商户系统: 1.1.2: 返回授权成功的同步结果，code=10000
    deactivate 商户系统
    支付宝服务端-->>支付宝客户端: 2: 返回授权成功结果页和发送支付宝消息
    deactivate 支付宝客户端
    deactivate 支付宝服务端

```
<a name="dsi7L"></a>
#### 验密模式
```
sequenceDiagram
    actor 用户
    participant 支付宝客户端
    participant 商户系统
    participant 支付宝服务端

    用户->>支付宝客户端: 1: 打开"支付宝"，选择付款
    支付宝客户端->>商户系统: 1.1: 通过扫码设备输入付款码
    商户系统->>支付宝服务端: 1.1.1: 调用alipay.fund.auth.order.freeze发起资金授权冻结操作
		支付宝服务端->>支付宝服务端: 1.1.1.1: 免密支付规则校验
    支付宝服务端-->>商户系统: 1.1.2: 返回授权成功的同步结果，code=10003
    
    支付宝服务端->>支付宝客户端: 2: 唤起支付宝收银台
    用户->>支付宝客户端: 3: 用户确认授权，输入密码
    支付宝客户端->>支付宝服务端: 3.1: 提交支付宝进行资金授权
    支付宝服务端-->>支付宝客户端: 3.2: 返回授权成功结果页和发送支付宝消息

    rect rgb(191, 223, 255)
    note over 商户系统: 商户端根据结果做相应处理
        loop 轮询结果，查询返回授权成功或者超时轮询超时时间30s
            商户系统->>支付宝服务端: 4: 调用alipay.fund.auth.operation.detail.query查询资金操作状态
            支付宝服务端-->>商户系统: 4.1：同步返回查询结果，<br/>冻结成功判断标准：status="SUCCESS"
        end

        alt 轮询时间超过30s仍未获取到授权成功结果
            商户系统->>支付宝服务端: 5：调用alipay.fund.auth.operation.cancel撤销该笔冻结操作
            支付宝服务端-->>商户系统: 5.1: 同步返回撤销结果
        end
    end

```
<a name="pQp8l"></a>
#### 请求示例
```java
package com.java.sdk.demo;

import com.alipay.api.AlipayApiException;
import com.alipay.api.AlipayClient;
import com.alipay.api.DefaultAlipayClient;
import com.alipay.api.AlipayConfig;
import com.alipay.api.request.AlipayFundAuthOrderFreezeRequest;
import com.alipay.api.domain.AlipayFundAuthOrderFreezeModel;
import com.alipay.api.domain.PostPayment;
import com.alipay.api.response.AlipayFundAuthOrderFreezeResponse;

import com.alipay.api.FileItem;
import java.util.Base64;
import java.util.ArrayList;
import java.util.List;

public class AlipayFundAuthOrderFreeze {

    public static void main(String[] args) throws AlipayApiException {
        // 初始化SDK
        AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig());

        // 构造请求参数以调用接口
        AlipayFundAuthOrderFreezeRequest request = new AlipayFundAuthOrderFreezeRequest();
        AlipayFundAuthOrderFreezeModel model = new AlipayFundAuthOrderFreezeModel();
        
        // 设置后付费项目
        List<PostPayment> postPayments = new ArrayList<PostPayment>();
        PostPayment postPayments0 = new PostPayment();
        postPayments0.setAmount("0.01");
        postPayments0.setName("租金");
        postPayments0.setDescription("2元/小时，99元封顶");
        postPayments.add(postPayments0);
        model.setPostPayments(postPayments);
        
        // 设置订单标题
        model.setOrderTitle("XX租车押金");
        
        // 设置需要冻结的金额
        model.setAmount("0.01");
        
        // 设置收款账户的支付宝用户号
        model.setPayeeUserId("2088102000275795");
        
        // 设置商户授权资金订单号
        model.setOutOrderNo("8077735255938023");
        
        // 设置销售产品码
        model.setProductCode("PREAUTH_PAY");
        
        // 设置收款账户的支付宝登录号（email或手机号）
        model.setPayeeLogonId("159****5620");
        
        // 设置用户付款码
        model.setAuthCode("付款码场景：28763443825664394，刷脸场景：fp1394da8bfc3e299a2128b8bda17456h84");
        
        // 设置无特殊需要请勿传入
        model.setEnablePayChannels("[{\"payChannelType\":\"PCREDIT_PAY\"},{\"payChannelType\":\"MONEY_FUND\"}]");
        
        // 设置免押受理台模式
        model.setDepositProductMode("POSTPAY");
        
        // 设置付款码类型
        model.setAuthCodeType("bar_code");
        
        // 设置业务参数
        model.setBusinessParams("{\"outRiskInfo\":\"{\"mcCreateTradeTime\":\"2022-03-11 12:46:09\",\"extraAccountCertnoLastSix\":\"000011\",\"mobileOperatingPlatform\":\"ios\",\"sysVersion\":\"15.4.2\",\"mcCreateTradeIp\":\"11.110.111.43\"}\"}");
        
        // 设置预授权订单相对超时时间
        model.setTimeoutExpress("2d");
        
        // 设置无特殊需要请勿传入
        model.setDisablePayChannels("[{\"payChannelType\":\"OPTIMIZED_MOTO\"},{\"payChannelType\":\"BIGAMOUNT_CREDIT_CARTOON\"}]");
        
        // 设置场景码
        model.setSceneCode("HOTEL");
        
        // 设置商户本次资金操作的请求流水号
        model.setOutRequestNo("8077735255938032");
        
        // 设置业务扩展参数
        model.setExtraParam("{\"category\":\"CHARGE_PILE_CAR\",\"serviceId\":\"2020042800000000000001450466\"}");
        
        request.setBizModel(model);
        // 第三方代调用模式下请设置app_auth_token
        // request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->");

        AlipayFundAuthOrderFreezeResponse response = alipayClient.execute(request);
        System.out.println(response.getBody());

        if (response.isSuccess()) {
            System.out.println("调用成功");
        } else {
            System.out.println("调用失败");
            // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接
            // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response);
            // System.out.println(diagnosisUrl);
        }
    }

    private static AlipayConfig getAlipayConfig() {
        String privateKey  = "<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->";
        String alipayPublicKey = "<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->";
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey(privateKey);
        alipayConfig.setFormat("json");
        alipayConfig.setAlipayPublicKey(alipayPublicKey);
        alipayConfig.setCharset("UTF-8");
        alipayConfig.setSignType("RSA2");
        return alipayConfig;
    }
}
```
<a name="wMaKm"></a>
#### 重要入参说明
| **参数英文名** | **描述** |
| --- | --- |
| out_order_no | 商户授权资金订单号。<br />商家自定义需保证在商户端不重复。仅支持字母、数字、下划线。 |
| out_request_no | 商户本次资金操作的请求流水号，用于标示请求流水的唯一性。<br />可与 out_order_no 相同，仅支持字母、数字、下划线。 |
| auth_code | 用户付款码。 |
| auth_code_type | 固定值传入 bar_code。 |
| order_title | 订单标题。 |
| amount | 冻结金额。 |
| payee_logon_id | 收款方支付宝账号（Email 或手机号）。如果收款方支付宝登录号（payee_logon_id）和用户号（payee_user_id）同时传递，则以用户号（payee_user_id）为准，如果商家要支持花呗渠道，收款方支付宝登录号（payee_logon_id）和用户号（payee_user_id）不能同时为空。 |
| payee_user_id | 收款方的支付宝唯一用户号，以 2088 开头的 16 位纯数字组成，如果非空则会在支付时校验交易的收款方与此是否一致，如果商家要支持花呗渠道，收款方支付宝登录号（payee_logon_id）和用户号（payee_user_id）不能同时为空。 |
| product_code | 销售产品码，新接入预授权支付业务，本字段取值固定为 PREAUTH_PAY。 |
| enable_pay_channels | 商家可用该参数指定用户可使用的支付渠道，本期支持三种支付渠道，余额宝（MONEY_FUND）、花呗（PCREDIT_PAY）以及芝麻信用（CREDITZHIMA）。商家可设置一种支付渠道，也可设置多种支付渠道。参数值格式为：[{"payChannelType":"PCREDIT_PAY"},{"payChannelType":"MONEY_FUND"},{"payChannelType":"CREDITZHIMA"}] 。 |
| extra_param | 业务扩展参数，用于商家的特定业务信息的传递，JSON 格式。<br />- 间联模式必须传入二级商户 ID，key 为 secondaryMerchantId。<br />- 预授权支付业务对应的类目，信用预授权必传。key 为 category，value 由支付宝分配。<br />   - 酒店业务传 HOTEL。<br />   - 充电桩业务传 CHARGE_PILE_CAR。<br />   - 传统租车传 TRAD_RENT_CAR。<br />- 外部商户的门店编号，key 为 outStoreCode，当需要支持信用授权时必传。<br />- 外部商户的门店简称，key 为 outStoreAlias，当需要支持信用授权时必传。<br /> |

**注意**：商户授权订单号 out_order_no 和资金操作流水号 out_request_no 在任何情况下不可重复，即使对于失败或撤销的授权冻结操作，商户授权订单号和资金操作流水号也可能已经被使用了，如需再次发起授权，必须使用新的商户授权订单号和资金操作流水号调用接口，否则会报错；order_title（业务订单标题），请准确描述实际消费订单说明，如发生和实际消费场景不匹配的说明，造成不必要的客诉，会影响到正常的服务使用。
<a name="Ub9d5"></a>
#### 重要出参说明
如商家有花呗渠道，必须保存返回信息中的 auth_no、payer_user_id。

| **参数英文名** | **描述** |
| --- | --- |
| auth_no | 支付宝 28 位授权资金订单号。 |
| operation_id | 支付宝标识本次资金操作的流水号。 |
| status | 本次资金授权操作的状态。 |
| pre_auth_type | 授权类型，目前支持 CREDIT_AUTH(信用授权)。商家可根据该标识来判断该笔类型，当返回值为 CREDIT_AUTH 表明该笔为信用授权，没有真实冻结资金；当返回值为空或者不为 CREDIT_AUTH 则表明该笔为普通资金授权，有冻结用户资金。 |

**注意**：**免密模式 **和 **验密模式** 可根据公共返回参数中的 code 做相应后续业务处理。这笔授权操作可能有四种状态：授权成功（10000），授权失败（40004），等待用户授权（10003）和未知异常（20000）。

| **结果码** | **描述** | **处理方式** |
| --- | --- | --- |
| 10000 | 授权成功 | 记录授权结果并在客户端显示授权成功，进入后续的业务处理。 |
| 40004 | 授权失败 | 记录授权结果并在终端显示错误信息（display_message)。 |
| 10003 | 等待用户授权 | 发起轮询流程：等待 5 秒后调用 [alipay.fund.auth.operation.detail.query](https://ideservice.alipay.com/cms/site/0izcu9)（资金授权操作查询接口） 通过授权时传入的商户授权订单号(out_order_no)和资金操作流水号(out_request_no)查询授权结果（返回参数 status），如果仍然返回等待用户授权（INIT），则再次等待5秒后继续查询，直到返回确切的授权结果（成功 SUCCESS 或已关闭 CLOSED），或是超出轮询时间（建议轮询时间为30s）。<br />**注意**：在最后一次查询仍然返回等待用户授权的情况下，必须立即调用 [alipay.fund.auth.operation.cancel](https://ideservice.alipay.com/cms/site/0iziyg)（资金授权撤销接口） 将这笔授权操作撤销，避免用户继续操作。 |
| 20000 | 未知异常 | 调用查询接口确认授权结果，详情可查看常见问题。 |

<a name="LPSeQ"></a>
### 用户扫商家二维码
```
sequenceDiagram
    actor 用户 as 用户
    participant 支付宝客户端 as 支付宝客户端
    participant 商户系统 as 商户系统
    participant 支付宝服务端 as 支付宝服务端

    %% 订单码生成阶段
    商户系统->>支付宝服务端: 1: 调用alipay.fund.auth.order.voucher.create生成订单码
    支付宝服务端-->>商户系统: 1.1: 返回订单码
    商户系统-->>用户: 1.2: 展示订单码给用户

    %% 用户授权阶段
    用户->>支付宝客户端: 2: 扫描商户的订单码
    支付宝客户端->>支付宝服务端: 2.1: 输入密码，提交支付宝进行资金授权
    支付宝服务端-->>支付宝客户端: 2.2: 返回授权成功结果页和发送支付宝消息通知

    %% 商户处理阶段
    rect rgb(191, 223, 255)
    note over 商户系统,支付宝服务端: 商户端根据结果做相应处理
        loop 轮询结果，查询返回授权成功或者超过轮询超时时间30s
            商户系统->>支付宝服务端: 3: 调用alipay.fund.auth.operation.detail.query查询资金操作状态
            支付宝服务端-->>商户系统: 3.1: 同步返回查询结果<br/>冻结成功判断标准：status="SUCCESS"<br/>
        end

        opt 轮询时间超过30秒仍未获取到授权成功结果）
            商户系统->>支付宝服务端: 4: 调用alipay.fund.auth.operation.cancel撤销该笔冻结操作
            支付宝服务端-->>商户系统: 4.1: 同步返回撤销结果
        end
    end

```
收银员通过收银台或商家后台调用 [alipay.fund.auth.order.voucher.create](https://ideservice.alipay.com/cms/site/0izf6b)（资金授权发码接口），生成二维码后，展示给用户，由用户扫描二维码完成资金冻结。

- 授权冻结支持的支付渠道以及默认冻结顺序：如果用户在支付宝客户端有设置默认扣款顺序，则以用户设置为准；如果用户未在支付宝客户端设置默认扣款顺序，则按照 **系统自定义** 的顺序扣款。
- 授权验证密码规则：用户通过支付宝客户端输入密码进行授权冻结。
<a name="MNivs"></a>
#### 请求示例
```java
package com.java.sdk.demo;

import com.alipay.api.AlipayApiException;
import com.alipay.api.AlipayClient;
import com.alipay.api.DefaultAlipayClient;
import com.alipay.api.AlipayConfig;
import com.alipay.api.request.AlipayFundAuthOrderVoucherCreateRequest;
import com.alipay.api.response.AlipayFundAuthOrderVoucherCreateResponse;
import com.alipay.api.domain.PostPayment;
import com.alipay.api.domain.AlipayFundAuthOrderVoucherCreateModel;

import com.alipay.api.FileItem;
import java.util.Base64;
import java.util.ArrayList;
import java.util.List;

public class AlipayFundAuthOrderVoucherCreate {

    public static void main(String[] args) throws AlipayApiException {
        // 初始化SDK
        AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig());

        // 构造请求参数以调用接口
        AlipayFundAuthOrderVoucherCreateRequest request = new AlipayFundAuthOrderVoucherCreateRequest();
        AlipayFundAuthOrderVoucherCreateModel model = new AlipayFundAuthOrderVoucherCreateModel();
        
        // 设置后付费项目
        List<PostPayment> postPayments = new ArrayList<PostPayment>();
        PostPayment postPayments0 = new PostPayment();
        postPayments0.setAmount("0.01");
        postPayments0.setName("租金");
        postPayments0.setDescription("2元/小时，99元封顶");
        postPayments.add(postPayments0);
        model.setPostPayments(postPayments);
        
        // 设置订单标题
        model.setOrderTitle("预授权发码");
        
        // 设置需要冻结的金额
        model.setAmount("100.00");
        
        // 设置收款账户的支付宝用户号
        model.setPayeeUserId("2088102000275795");
        
        // 设置商户授权资金订单号
        model.setOutOrderNo("8077735255938023");
        
        // 设置销售产品码
        model.setProductCode("PREAUTH_PAY");
        
        // 设置收款账户的支付宝登录号（email或手机号）
        model.setPayeeLogonId("159****5620");
        
        // 设置无特殊需要请勿传入
        model.setEnablePayChannels("[{\"payChannelType\":\"PCREDIT_PAY\"},{\"payChannelType\":\"MONEY_FUND\"}]");
        
        // 设置免押受理台模式
        model.setDepositProductMode("POSTPAY");
        
        // 设置无特殊需要请勿传入
        model.setIdentityParams("{\"identity_hash\":\"acc2b92ffc5ed9b472faa19748f10045c30434132784f774b00216a56b8841c6\",\"alipay_open_id\":\"xxxxxx\",\"alipay_user_id\":\"2088xxx\"}");
        
        // 设置业务参数
        model.setBusinessParams("{\"outRiskInfo\":\"{\"mcCreateTradeTime\":\"2022-03-11 12:46:09\",\"extraAccountCertnoLastSix\":\"000011\",\"mobileOperatingPlatform\":\"ios\",\"sysVersion\":\"15.4.2\",\"mcCreateTradeIp\":\"11.110.111.43\"}\"}");
        
        // 设置预授权订单相对超时时间
        model.setTimeoutExpress("2d");
        
        // 设置无特殊需要请勿传入
        model.setDisablePayChannels("[{\"payChannelType\":\"OPTIMIZED_MOTO\"},{\"payChannelType\":\"BIGAMOUNT_CREDIT_CARTOON\"}]");
        
        // 设置商户本次资金操作的请求流水号
        model.setOutRequestNo("8077735255938032");
        
        // 设置业务扩展参数
        model.setExtraParam("{\"category\":\"CHARGE_PILE_CAR\",\"serviceId\":\"2020042800000000000001450466\"}");
        
        request.setBizModel(model);
        // 第三方代调用模式下请设置app_auth_token
        // request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->");

        AlipayFundAuthOrderVoucherCreateResponse response = alipayClient.execute(request);
        System.out.println(response.getBody());

        if (response.isSuccess()) {
            System.out.println("调用成功");
        } else {
            System.out.println("调用失败");
            // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接
            // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response);
            // System.out.println(diagnosisUrl);
        }
    }

    private static AlipayConfig getAlipayConfig() {
        String privateKey  = "<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->";
        String alipayPublicKey = "<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->";
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey(privateKey);
        alipayConfig.setFormat("json");
        alipayConfig.setAlipayPublicKey(alipayPublicKey);
        alipayConfig.setCharset("UTF-8");
        alipayConfig.setSignType("RSA2");
        return alipayConfig;
    }
}
```
<a name="Q1FpK"></a>
#### 重要入参说明
| **参数英文名** | **描述** |
| --- | --- |
| out_order_no | 商户授权资金订单号，需要保证不重复。 |
| out_request_no | 商户授权资金操作流水号，需要保证不重复。 |
| order_title | 订单标题。 |
| amount | 冻结金额。 |
| payee_logon_id | 收款方支付宝账号（Email 或手机号），如果收款方支付宝登录号（payee_logon_id）和用户号（payee_user_id）同时传递，则以用户号（payee_user_id）为准，如果商家要支持花呗渠道，收款方支付宝登录号（payee_logon_id）和用户号（payee_user_id）不能同时为空。 |
| payee_user_id | 收款方的支付宝唯一用户号，以 2088 开头的 16 位纯数字组成，如果非空则会在支付时校验交易的收款方与此是否一致，如果商家要支持花呗渠道，收款方支付宝登录号（payee_logon_id）和用户（payee_user_id）不能同时为空。 |
| enable_pay_channels | 商家可用该参数指定用户可使用的支付渠道，本期支持三种支付渠道，余额宝（MONEY_FUND）、花呗（PCREDIT_PAY）以及芝麻信用（CREDITZHIMA）。商家可设置一种支付渠道，也可设置多种支付渠道。参数值格式为：[{"payChannelType":"PCREDIT_PAY"},{"payChannelType":"MONEY_FUND"},{"payChannelType":"CREDITZHIMA"}] 。 |
| product_code | 销售产品码，新接入预授权支付业务，本字段取值固定为 PREAUTH_PAY。 |
| extra_param | 业务扩展参数，用于商家的特定业务信息的传递，JSON 格式。<br />- 间联模式必须传入二级商户 ID，key 为 secondaryMerchantId。<br />- 预授权支付业务对应的类目，信用预授权必传。key 为 category，value 由支付宝分配：<br />   - 酒店业务传 HOTEL。<br />   - 充电桩业务传 CHARGE_PILE_CAR。<br />   - 传统租车传 TRAD_RENT_CAR。<br />- 外部商户的门店编号，key 为 outStoreCode，当需要支持信用授权时必传。<br />- 外部商户的门店简称，key 为 outStoreAlias，当需要支持信用授权时必传。<br /> |

<a name="lAVDn"></a>
#### 重要出参说明
| **参数英文名** | **描述** |
| --- | --- |
| out_order_no | 商户的授权资金订单号。 |
| out_request_no | 商户本次资金操作的请求流水号。 |
| code_type | 码类型，分为 barCode：条形码 (一维码) 和 qrCode：二维码(qrCode) ；目前发码只支持 qrCode。 |
| code_value | 当前发码请求生成的二维码码串，商户端可以利用二维码生成工具根据该码串值生成对应的二维码。 |
| code_url | 生成的带有支付宝 logo 的二维码地址。 |

<a name="TdSYf"></a>
## 查询资金冻结操作
商家调用 [alipay.fund.auth.operation.detail.query](https://ideservice.alipay.com/cms/site/0izcu9)（资金授权操作查询接口） 可以查询单笔资金授权操作的详细信息。
<a name="yAkMg"></a>
### 请求示例
```java
package com.java.sdk.demo;

import com.alipay.api.AlipayApiException;
import com.alipay.api.AlipayClient;
import com.alipay.api.DefaultAlipayClient;
import com.alipay.api.AlipayConfig;
import com.alipay.api.request.AlipayFundAuthOperationDetailQueryRequest;
import com.alipay.api.response.AlipayFundAuthOperationDetailQueryResponse;
import com.alipay.api.domain.AlipayFundAuthOperationDetailQueryModel;

import com.alipay.api.FileItem;
import java.util.Base64;
import java.util.ArrayList;
import java.util.List;

public class AlipayFundAuthOperationDetailQuery {

    public static void main(String[] args) throws AlipayApiException {
        // 初始化SDK
        AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig());

        // 构造请求参数以调用接口
        AlipayFundAuthOperationDetailQueryRequest request = new AlipayFundAuthOperationDetailQueryRequest();
        AlipayFundAuthOperationDetailQueryModel model = new AlipayFundAuthOperationDetailQueryModel();
        
        // 设置支付宝授权资金订单号
        model.setAuthNo("2014021601002000640012345678");
        
        // 设置商户的授权资金订单号
        model.setOutOrderNo("8077735255938023");
        
        // 设置支付宝的授权资金操作流水号
        model.setOperationId("20140216010020006400");
        
        // 设置商户的授权资金操作流水号
        model.setOutRequestNo("20140216001001");
        
        // 设置需要查询的授权资金操作类型
        model.setOperationType("FREEZE");
        
        request.setBizModel(model);
        // 第三方代调用模式下请设置app_auth_token
        // request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->");

        AlipayFundAuthOperationDetailQueryResponse response = alipayClient.execute(request);
        System.out.println(response.getBody());

        if (response.isSuccess()) {
            System.out.println("调用成功");
        } else {
            System.out.println("调用失败");
            // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接
            // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response);
            // System.out.println(diagnosisUrl);
        }
    }

    private static AlipayConfig getAlipayConfig() {
        String privateKey  = "<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->";
        String alipayPublicKey = "<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->";
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey(privateKey);
        alipayConfig.setFormat("json");
        alipayConfig.setAlipayPublicKey(alipayPublicKey);
        alipayConfig.setCharset("UTF-8");
        alipayConfig.setSignType("RSA2");
        return alipayConfig;
    }
}
```
<a name="Jh7wl"></a>
### 重要入参说明
| **参数英文名** | **描述** |
| --- | --- |
| auth_no | 支付宝 28 位授权资金订单号。 |
| operation_id | 支付宝资金授权冻结操作流水号。 |
| out_order_no | 商户资金授权订单号，需与资金冻结接口 out_order_no 一致。 |
| out_request_no | 商户资金授权冻结操作流水号，需与资金冻结接口 out_request_no 一致。 |

<a name="WBkvK"></a>
### 重要出参说明
| **参数英文名** | **描述** |
| --- | --- |
| auth_no | 支付宝 28 位授权资金订单号。 |
| operation_id | 支付宝资金授权冻结操作流水号。 |
| out_order_no | 商户资金授权订单号。 |
| out_request_no | 商户资金授权冻结操作流水号。 |
| status | 本次资金授权操作的状态。 |

<a name="asPe0"></a>
## 冻结资金转支付
```
sequenceDiagram
    participant 商户系统
    participant 支付宝服务端

    商户系统->>支付宝服务端: 1: 调用alipay.trade.pay创建交易单并进行授权资金解冻支付给卖家
    支付宝服务端-->>商户系统: 1.1: 返回交易支付结果
```
商家需要解冻用户授权资金并支付给卖家时，调用 [alipay.trade.pay](https://ideservice.alipay.com/cms/site/0izg0i)（统一收单交易支付接口） 创建交易订单将授权资金解冻转支付给卖家，并解冻剩余资金。<br />**注意**：

- 此过程无需再次扫描用户支付宝客户端付款码。
- 交易创建并支付的金额应小于等于用户授权资金金额，当支付金额小于授权冻结金额时，剩余授权冻结金额需要商家再发起授权资金解冻请求将剩余冻结资金进行解冻。
- 冻结资金转支付后如果有剩余冻结金额，如无必要，要求商家系统立即操作解冻，同时后台要开放人工单独解冻的入口。防止后续用户投诉，方便操作解冻。
<a name="LTPEV"></a>
### 请求示例
```java
package com.java.sdk.demo;

import com.alipay.api.AlipayApiException;
import com.alipay.api.AlipayClient;
import com.alipay.api.DefaultAlipayClient;
import com.alipay.api.AlipayConfig;
import com.alipay.api.domain.PromoParam;
import com.alipay.api.response.AlipayTradePayResponse;
import com.alipay.api.domain.AlipayTradePayModel;
import com.alipay.api.domain.ExtendParams;
import com.alipay.api.domain.GoodsDetail;
import com.alipay.api.request.AlipayTradePayRequest;

import com.alipay.api.FileItem;
import java.util.Base64;
import java.util.ArrayList;
import java.util.List;

public class AlipayTradePay {

    public static void main(String[] args) throws AlipayApiException {
        // 初始化SDK
        AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig());

        // 构造请求参数以调用接口
        AlipayTradePayRequest request = new AlipayTradePayRequest();
        AlipayTradePayModel model = new AlipayTradePayModel();
        
        // 设置商户订单号
        model.setOutTradeNo("20150320010101001");
        
        // 设置订单总金额
        model.setTotalAmount("88.88");
        
        // 设置订单标题
        model.setSubject("XX租车租金");
        
        // 设置产品码
        model.setProductCode("PREAUTH_PAY");
        
        // 设置资金预授权单号
        model.setAuthNo("2016110310002001760201905725");
        
        // 设置预授权确认模式
        model.setAuthConfirmMode("COMPLETE");
        
        // 设置订单包含的商品列表信息
        List<GoodsDetail> goodsDetail = new ArrayList<GoodsDetail>();
        GoodsDetail goodsDetail0 = new GoodsDetail();
        goodsDetail0.setGoodsName("ipad");
        goodsDetail0.setQuantity(1L);
        goodsDetail0.setPrice("2000");
        goodsDetail0.setGoodsId("apple-01");
        goodsDetail0.setGoodsCategory("34543238");
        goodsDetail0.setCategoriesTree("124868003|126232002|126252004");
        goodsDetail0.setShowUrl("http://www.alipay.com/xxx.jpg");
        goodsDetail.add(goodsDetail0);
        model.setGoodsDetail(goodsDetail);
        
        // 设置业务扩展参数
        ExtendParams extendParams = new ExtendParams();
        extendParams.setSysServiceProviderId("2088511833207846");
        extendParams.setCardType("S0JP0000");
        model.setExtendParams(extendParams);
        
        // 设置优惠明细参数
        PromoParam promoParams = new PromoParam();
        promoParams.setActualOrderTime("2018-09-25 22:47:33");
        model.setPromoParams(promoParams);
        
        // 设置商户门店编号
        model.setStoreId("NJ_001");
        
        // 设置商户机具终端编号
        model.setTerminalId("NJ_T_001");
        
        // 设置返回参数选项
        List<String> queryOptions = new ArrayList<String>();
        queryOptions.add("voucher_detail_list");
        model.setQueryOptions(queryOptions);
        
        request.setBizModel(model);
        // 第三方代调用模式下请设置app_auth_token
        // request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->");

        AlipayTradePayResponse response = alipayClient.execute(request);
        System.out.println(response.getBody());

        if (response.isSuccess()) {
            System.out.println("调用成功");
        } else {
            System.out.println("调用失败");
            // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接
            // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response);
            // System.out.println(diagnosisUrl);
        }
    }

    private static AlipayConfig getAlipayConfig() {
        String privateKey  = "<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->";
        String alipayPublicKey = "<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->";
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey(privateKey);
        alipayConfig.setFormat("json");
        alipayConfig.setAlipayPublicKey(alipayPublicKey);
        alipayConfig.setCharset("UTF-8");
        alipayConfig.setSignType("RSA2");
        return alipayConfig;
    }
}
```
<a name="uUruq"></a>
### 重要入参说明
| **参数英文名** | **描述** |
| --- | --- |
| out_trade_no | 商户订单号，需要保证不重复。 |
| total_amount | 订单金额。 |
| product_code | 产品码，预授权支付场景传固定值 PREAUTH_PAY。 |
| auth_no | 支付宝资金授权单号。 |
| subject | 订单标题。 |
| auth_confirm_mode | 预授权转交易时结束预授权（并解冻剩余资金）时需要传入COMPLETE 或 NOT_COMPLETE。<br />- 当传入 COMPLETE 时，执行转支付给收款方并剩余授权资金解除。<br />- 当传入 NOT_COMPLETE 或不传时，仅执行转支付给收款方。<br /> |
| business_params | 商家传入业务信息，具体值要和支付宝约定。非必传。<br />信用预授权场景可传入具体订单信息，具体示例值：<br />`{"orderBizInfo":"{\\"ChargeType\\":\\"rent\\",\\"PenaltyPoints\\":\\\\"3分"}"}`。 |
| store_id | 资金授权场景必传，商户门店编号。 |
| terminal_id | 资金授权场景必传，商户机具终端编号。 |
| +extend_params | 业务扩展参数，可选。 |
| └sys_service_provider_id | 系统商编号，该参数作为系统商返佣数据提取的依据，请填写系统商签约协议的 PID。<br />示例值：`"extend_params":{"sys_service_provider_id":"ISV签约账户的PID"}`。 |

**说明**：商户订单号 out_trade_no 在任何情况下不可重复，即使对于失败或撤销的交易，商户订单号也可能已经被使用了，如需再次发起支付，必须使用新的商户订单号调用接口，否则会报错；subject（业务订单标题），请准确描述实际消费订单说明，避免发生和实际消费场景不匹配的说明，造成客诉，影响正常的服务使用。
<a name="ljPgO"></a>
## 解冻资金
```
sequenceDiagram
    participant 商户系统
    participant 支付宝服务端

    商户系统->>支付宝服务端: 1: 调用alipay.fund.auth.order.unfreeze发起资金授权解冻
    支付宝服务端-->>商户系统: 1.1: 返回解冻结果
```
商家需要解冻用户授权资金时，可调用 [alipay.fund.auth.order.unfreeze](https://ideservice.alipay.com/cms/site/0izg0h)（资金授权解冻接口） 请求退款，并同步获得退款结果。支持部分解冻。冻结订单的资金解冻都需要由商家端发起，支付宝不会对冻结资金自动解冻。<br />**注意**：解冻服务中的附言 remark 字段会展示在用户的支付宝账单上。
<a name="Y1hfJ"></a>
### 请求示例
```java
package com.java.sdk.demo;

import com.alipay.api.AlipayApiException;
import com.alipay.api.AlipayClient;
import com.alipay.api.DefaultAlipayClient;
import com.alipay.api.AlipayConfig;
import com.alipay.api.domain.AlipayFundAuthOrderUnfreezeModel;
import com.alipay.api.request.AlipayFundAuthOrderUnfreezeRequest;
import com.alipay.api.response.AlipayFundAuthOrderUnfreezeResponse;

import com.alipay.api.FileItem;
import java.util.Base64;
import java.util.ArrayList;
import java.util.List;

public class AlipayFundAuthOrderUnfreeze {

    public static void main(String[] args) throws AlipayApiException {
        // 初始化SDK
        AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig());

        // 构造请求参数以调用接口
        AlipayFundAuthOrderUnfreezeRequest request = new AlipayFundAuthOrderUnfreezeRequest();
        AlipayFundAuthOrderUnfreezeModel model = new AlipayFundAuthOrderUnfreezeModel();
        
        // 设置支付宝资金授权订单号
        model.setAuthNo("2016101210002001810258115912");
        
        // 设置解冻请求流水号
        model.setOutRequestNo("2016101200104001110081001");
        
        // 设置本次操作解冻的金额
        model.setAmount("20.11");
        
        // 设置商户对本次解冻操作的附言描述
        model.setRemark("2014-05期解冻200.00元");
        
        // 设置解冻扩展信息
        model.setExtraParam("{\"unfreezeBizInfo\": \"{\"bizComplete\":\"true\"}\"}");
        
        request.setBizModel(model);
        // 第三方代调用模式下请设置app_auth_token
        // request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->");

        AlipayFundAuthOrderUnfreezeResponse response = alipayClient.execute(request);
        System.out.println(response.getBody());

        if (response.isSuccess()) {
            System.out.println("调用成功");
        } else {
            System.out.println("调用失败");
            // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接
            // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response);
            // System.out.println(diagnosisUrl);
        }
    }

    private static AlipayConfig getAlipayConfig() {
        String privateKey  = "<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->";
        String alipayPublicKey = "<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->";
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey(privateKey);
        alipayConfig.setFormat("json");
        alipayConfig.setAlipayPublicKey(alipayPublicKey);
        alipayConfig.setCharset("UTF-8");
        alipayConfig.setSignType("RSA2");
        return alipayConfig;
    }
}
```
<a name="HuMMi"></a>
### 重要入参说明
| **参数英文名** | **描述** |
| --- | --- |
| auth_no | 支付宝 28 位授权资金订单号。 |
| out_request_no | 解冻请求流水号。<br />如果是针对同一笔授权单不同的解冻请求，如第一次解冻1元，第二次解冻2元，则解冻请求流水号必须不重复；<br />如果是针对同一笔解冻请求的多次发起，则需要保证每次发起，解冻请求流水号和解冻金额都相同。 |
| amount | 本次操作解冻的金额，单位为：元（人民币），精确到小数点后两位。<br />取值范围：[0.01,100000000.00] |
| remark | 操作描述，展示在用户支付宝账单上。 |
| extra_param  | 解冻扩展信息，JSON 格式。<br />具体示例值：`{"unfreezeBizInfo": "{\\"bizComplete\\":\\"true\\"}"}`<br />unfreezeBizInfo 目前为芝麻消费字段，支持 Key 值如下： bizComplete：true。选填：标识本次解冻用户是否履约，如果 true 信用单会完结为 COMPLETE。 |

**注意**：解冻接口会根据商家的资金操作流水号 out_request_no 幂等返回，因此必须保证每次资金操作时需要使用不同的 out_request_no。
<a name="baIAu"></a>
### 重要出参说明
| **参数英文名** | **描述** |
| --- | --- |
| auth_no | 支付宝 28 位授权资金订单号。 |
| operation_id | 支付宝标识本次资金操作的流水号。 |
| status | 本次资金授权操作的状态。 |

<a name="IAztv"></a>
## 撤销资金授权
商家业务系统处理超时，需要终止后续业务处理或者授权结果未知，且调用 [alipay.fund.auth.operation.detail.query](https://ideservice.alipay.com/cms/site/0izcu9)（资金授权操作查询接口） 没有明确的授权结果时，可调用 [alipay.fund.auth.operation.cancel](https://ideservice.alipay.com/cms/site/0iziyg)（资金授权撤销接口）撤销资金授权。<br />**注意**：正常授权冻结的操作如需实现相同功能请调用 [alipay.fund.auth.order.unfreeze](https://ideservice.alipay.com/cms/site/0izg0h)（资金授权解冻接口）。
<a name="i3GzC"></a>
### 请求示例
```java
package com.java.sdk.demo;

import com.alipay.api.AlipayApiException;
import com.alipay.api.AlipayClient;
import com.alipay.api.DefaultAlipayClient;
import com.alipay.api.AlipayConfig;
import com.alipay.api.request.AlipayFundAuthOperationCancelRequest;
import com.alipay.api.response.AlipayFundAuthOperationCancelResponse;
import com.alipay.api.domain.AlipayFundAuthOperationCancelModel;

import com.alipay.api.FileItem;
import java.util.Base64;
import java.util.ArrayList;
import java.util.List;

public class AlipayFundAuthOperationCancel {

    public static void main(String[] args) throws AlipayApiException {
        // 初始化SDK
        AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig());

        // 构造请求参数以调用接口
        AlipayFundAuthOperationCancelRequest request = new AlipayFundAuthOperationCancelRequest();
        AlipayFundAuthOperationCancelModel model = new AlipayFundAuthOperationCancelModel();
        
        // 设置支付宝授权资金订单号
        model.setAuthNo("2014070800002001550000014417");
        
        // 设置商户的授权资金订单号
        model.setOutOrderNo("4977164666634053");
        
        // 设置支付宝的授权资金操作流水号
        model.setOperationId("20161012405744018102");
        
        // 设置商户的授权资金操作流水号
        model.setOutRequestNo("2016100810000003551");
        
        // 设置商户对本次撤销操作的附言描述
        model.setRemark("授权撤销");
        
        request.setBizModel(model);
        // 第三方代调用模式下请设置app_auth_token
        // request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->");

        AlipayFundAuthOperationCancelResponse response = alipayClient.execute(request);
        System.out.println(response.getBody());

        if (response.isSuccess()) {
            System.out.println("调用成功");
        } else {
            System.out.println("调用失败");
            // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接
            // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response);
            // System.out.println(diagnosisUrl);
        }
    }

    private static AlipayConfig getAlipayConfig() {
        String privateKey  = "<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->";
        String alipayPublicKey = "<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->";
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey(privateKey);
        alipayConfig.setFormat("json");
        alipayConfig.setAlipayPublicKey(alipayPublicKey);
        alipayConfig.setCharset("UTF-8");
        alipayConfig.setSignType("RSA2");
        return alipayConfig;
    }
}
```
<a name="VKA5U"></a>
### 重要入参说明
| **参数英文名** | **描述** |
| --- | --- |
| auth_no | 支付宝 28 位授权资金订单号。 |
| operation_id | 支付宝资金授权冻结操作流水号。 |
| out_order_no | 商户资金授权订单号，需与资金冻结接口 out_order_no 一致。 |
| out_request_no | 商户资金授权冻结操作流水号，需与资金冻结接口 out_request_no 一致。 |
| remark | 操作描述。 |

<a name="vyIdP"></a>
### 重要出参说明
| **参数英文名** | **描述** |
| --- | --- |
| action | 本次撤销触发的动作。<br />- close：关闭订单，无资金解冻。<br />- unfreeze：产生了资金解冻。<br /> |

<a name="UafMe"></a>
## 查询交易
```
sequenceDiagram
    participant 商户系统
    participant 支付宝服务端

    商户系统->>支付宝服务端: 1: 调用alipay.trade.query发起交易订单查询请求
    支付宝服务端-->>商户系统: 1.1: 返回交易订单查询结果
```
商家因后台、网络、服务器等出现异常，而未接收到支付异步通知时，可调用 [alipay.trade.query](https://ideservice.alipay.com/cms/site/0izhis)（统一收单交易查询接口），同步查询交易订单信息。
<a name="cobzP"></a>
### 请求示例
```java
package com.java.sdk.demo;

import com.alipay.api.AlipayApiException;
import com.alipay.api.AlipayClient;
import com.alipay.api.DefaultAlipayClient;
import com.alipay.api.AlipayConfig;
import com.alipay.api.response.AlipayTradeQueryResponse;
import com.alipay.api.request.AlipayTradeQueryRequest;
import com.alipay.api.domain.AlipayTradeQueryModel;

import com.alipay.api.FileItem;
import java.util.Base64;
import java.util.ArrayList;
import java.util.List;

public class AlipayTradeQuery {

    public static void main(String[] args) throws AlipayApiException {
        // 初始化SDK
        AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig());

        // 构造请求参数以调用接口
        AlipayTradeQueryRequest request = new AlipayTradeQueryRequest();
        AlipayTradeQueryModel model = new AlipayTradeQueryModel();
        
        // 设置订单支付时传入的商户订单号
        model.setOutTradeNo("20150320010101001");
        
        // 设置支付宝交易号
        model.setTradeNo("2014112611001004680 073956707");
        
        // 设置银行间联模式下有用
        model.setOrgPid("2088101117952222");
        
        // 设置查询选项
        List<String> queryOptions = new ArrayList<String>();
        queryOptions.add("trade_settle_info");
        model.setQueryOptions(queryOptions);
        
        request.setBizModel(model);
        // 第三方代调用模式下请设置app_auth_token
        // request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->");

        AlipayTradeQueryResponse response = alipayClient.execute(request);
        System.out.println(response.getBody());

        if (response.isSuccess()) {
            System.out.println("调用成功");
        } else {
            System.out.println("调用失败");
            // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接
            // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response);
            // System.out.println(diagnosisUrl);
        }
    }

    private static AlipayConfig getAlipayConfig() {
        String privateKey  = "<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->";
        String alipayPublicKey = "<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->";
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey(privateKey);
        alipayConfig.setFormat("json");
        alipayConfig.setAlipayPublicKey(alipayPublicKey);
        alipayConfig.setCharset("UTF-8");
        alipayConfig.setSignType("RSA2");
        return alipayConfig;
    }
}
```
<a name="PlcJi"></a>
### 重要入参说明
| **参数英文名** | **描述** |
| --- | --- |
| out_trade_no | 支付时传入的商户订单号，与 trade_no 必填一个。 |
| trade_no | 支付时返回的支付宝交易号，与 out_trade_no 必填一个。 |

<a name="XKUPu"></a>
### 重要出参说明
| **参数英文名** | **描述** |
| --- | --- |
| trade_no | 支付宝 28 位交易号。 |
| out_trade_no | 支付时传入的商户订单号。 |
| trade_status | 交易当前状态。 |

<a name="r6FQI"></a>
## 交易关闭
```
sequenceDiagram
    participant 商户系统
    participant 支付宝服务端

    商户系统->>支付宝服务端: 1: 调用alipay.trade.close发起交易订单关闭请求
    支付宝服务端-->>商户系统: 1.1: 返回交易订单关闭结果
```
交易创建后，用户在一定时间内未进行支付，商家可调用 [alipay.trade.close](https://ideservice.alipay.com/cms/site/0izhiq)（统一收单交易关闭接口） 直接将未付款的交易进行关闭。 
<a name="t6qDu"></a>
### 请求示例
```java
package com.java.sdk.demo;

import com.alipay.api.AlipayApiException;
import com.alipay.api.AlipayClient;
import com.alipay.api.DefaultAlipayClient;
import com.alipay.api.AlipayConfig;
import com.alipay.api.request.AlipayTradeCloseRequest;
import com.alipay.api.domain.AlipayTradeCloseModel;
import com.alipay.api.response.AlipayTradeCloseResponse;

import com.alipay.api.FileItem;
import java.util.Base64;
import java.util.ArrayList;
import java.util.List;

public class AlipayTradeClose {

    public static void main(String[] args) throws AlipayApiException {
        // 初始化SDK
        AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig());

        // 构造请求参数以调用接口
        AlipayTradeCloseRequest request = new AlipayTradeCloseRequest();
        AlipayTradeCloseModel model = new AlipayTradeCloseModel();
        
        // 设置该交易在支付宝系统中的交易流水号
        model.setTradeNo("2013112611001004680073956707");
        
        // 设置订单支付时传入的商户订单号
        model.setOutTradeNo("HZ0120131127001");
        
        // 设置商家操作员编号 id
        model.setOperatorId("YX01");
        
        request.setBizModel(model);
        // 第三方代调用模式下请设置app_auth_token
        // request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->");

        AlipayTradeCloseResponse response = alipayClient.execute(request);
        System.out.println(response.getBody());

        if (response.isSuccess()) {
            System.out.println("调用成功");
        } else {
            System.out.println("调用失败");
            // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接
            // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response);
            // System.out.println(diagnosisUrl);
        }
    }

    private static AlipayConfig getAlipayConfig() {
        String privateKey  = "<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->";
        String alipayPublicKey = "<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->";
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey(privateKey);
        alipayConfig.setFormat("json");
        alipayConfig.setAlipayPublicKey(alipayPublicKey);
        alipayConfig.setCharset("UTF-8");
        alipayConfig.setSignType("RSA2");
        return alipayConfig;
    }
}
```
<a name="gL7vL"></a>
### 重要入参说明
| **参数英文名** | **描述** |
| --- | --- |
| out_trade_no | 支付时传入的商户订单号，与 trade_no 必填一个。 |
| trade_no | 支付时返回的支付宝交易号，与 out_trade_no 必填一个。 |

<a name="zrLHZ"></a>
### 重要出参说明
| **参数英文名** | **描述** |
| --- | --- |
| trade_no | 支付宝 28 位交易号。 |
| out_trade_no | 支付时传入的商户订单号。 |

<a name="wu4NF"></a>
## 订单信息同步
```
sequenceDiagram
    participant 商户系统
    participant 支付宝服务端

    商户系统->>支付宝服务端: 1: 调用alipay.trade.orderinfo.sync发起交易信息同步请求
    支付宝服务端-->>商户系统: 1.1: 返回交易信息同步结果
```
商家可调用 [alipay.trade.orderinfo.sync](https://ideservice.alipay.com/cms/site/0izhit)（支付宝订单信息同步接口），传入该笔订单相关同步信息。
<a name="ynUpd"></a>
### 请求示例
```java
package com.java.sdk.demo;

import com.alipay.api.AlipayApiException;
import com.alipay.api.AlipayClient;
import com.alipay.api.DefaultAlipayClient;
import com.alipay.api.AlipayConfig;
import com.alipay.api.request.AlipayTradeOrderinfoSyncRequest;
import com.alipay.api.domain.AlipayTradeOrderinfoSyncModel;
import com.alipay.api.response.AlipayTradeOrderinfoSyncResponse;

import com.alipay.api.FileItem;
import java.util.Base64;
import java.util.ArrayList;
import java.util.List;

public class AlipayTradeOrderinfoSync {

    public static void main(String[] args) throws AlipayApiException {
        // 初始化SDK
        AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig());

        // 构造请求参数以调用接口
        AlipayTradeOrderinfoSyncRequest request = new AlipayTradeOrderinfoSyncRequest();
        AlipayTradeOrderinfoSyncModel model = new AlipayTradeOrderinfoSyncModel();
        
        // 设置商户传入同步信息
        model.setOrderBizInfo("{\"status\":\"COMPLETE\"}");
        
        // 设置交易信息同步对应的业务类型
        model.setBizType("CREDIT_AUTH");
        
        // 设置支付宝交易号
        model.setTradeNo("2018061021001004680073956707");
        
        // 设置原始业务请求单号
        model.setOrigRequestNo("HZ01RF001");
        
        // 设置外部请求号
        model.setOutRequestNo("HZ01RF001");
        
        request.setBizModel(model);
        AlipayTradeOrderinfoSyncResponse response = alipayClient.execute(request);
        System.out.println(response.getBody());

        if (response.isSuccess()) {
            System.out.println("调用成功");
        } else {
            System.out.println("调用失败");
            // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接
            // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response);
            // System.out.println(diagnosisUrl);
        }
    }

    private static AlipayConfig getAlipayConfig() {
        String privateKey  = "<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->";
        String alipayPublicKey = "<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->";
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey(privateKey);
        alipayConfig.setFormat("json");
        alipayConfig.setAlipayPublicKey(alipayPublicKey);
        alipayConfig.setCharset("UTF-8");
        alipayConfig.setSignType("RSA2");
        return alipayConfig;
    }
}
```
<a name="z3HfN"></a>
### 重要入参说明
| **参数英文名** | **描述** |
| --- | --- |
| trade_no | 支付时返回的支付宝交易号，与 out_trade_no 必填一个。 |
| out_request_no | 外部请求号，商家多次同步信息时，需保证唯一。 |
| biz_type | 交易信息同步对应的业务类型，具体值与支付宝约定；<br />信用授权场景下传 CREDIT_AUTH |
| order_biz_info | 商家传入同步信息，具体值要和支付宝约定；用于芝麻信用租车、单次授权等信息同步场景，格式为 JSON。<br />**示例值**：`{\\"status\\":\\"COMPLETE\\"}`<br />**可选值**：<br />- 用户已违约：VIOLATED。<br />- 用户已履约：COMPLETE。<br />- 同步履约已取消：CLOSED。<br />- 开启用户支付入口：OPEN_PAY。<br /> |

<a name="JqzVe"></a>
### 重要出参说明
| **参数英文名** | **描述** |
| --- | --- |
| trade_no | 支付宝 28 位交易号。 |
| out_trade_no | 支付时传入的商户订单号。 |
| buyer_user_id | 买家在支付宝的用户 id。 |

<a name="YRtcu"></a>
# 退款流程
```
sequenceDiagram
    participant 商户系统
    participant 支付宝服务端

    商户系统->>支付宝服务端: 1: 调用alipay.trade.refund发起退款请求
    支付宝服务端-->>商户系统: 1.1: 返回退款结果
```
商家需要退款时，可调用 [alipay.trade.refund](https://ideservice.alipay.com/cms/site/0iziyj)（统一收单交易退款接口） 请求退款，并同步获得退款结果。支持部分退款。<br />**注意**：交易发生后，超过 12 个月则不可发起退款，退款成功后，资金原路返回用户账户。退款是否退费以交易发生时刻合约中的退费约定为准。
<a name="wkhBQ"></a>
## 请求示例
```java
package com.java.sdk.demo;

import com.alipay.api.AlipayApiException;
import com.alipay.api.AlipayClient;
import com.alipay.api.DefaultAlipayClient;
import com.alipay.api.AlipayConfig;
import com.alipay.api.domain.AlipayTradeRefundModel;
import com.alipay.api.request.AlipayTradeRefundRequest;
import com.alipay.api.response.AlipayTradeRefundResponse;
import com.alipay.api.domain.RefundGoodsDetail;
import com.alipay.api.domain.OpenApiRoyaltyDetailInfoPojo;

import com.alipay.api.FileItem;
import java.util.Base64;
import java.util.ArrayList;
import java.util.List;

public class AlipayTradeRefund {

    public static void main(String[] args) throws AlipayApiException {
        // 初始化SDK
        AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig());

        // 构造请求参数以调用接口
        AlipayTradeRefundRequest request = new AlipayTradeRefundRequest();
        AlipayTradeRefundModel model = new AlipayTradeRefundModel();
        
        // 设置商户订单号
        model.setOutTradeNo("20150320010101001");
        
        // 设置支付宝交易号
        model.setTradeNo("2014112611001004680073956707");
        
        // 设置退款金额
        model.setRefundAmount("200.12");
        
        // 设置退款原因说明
        model.setRefundReason("正常退款");
        
        // 设置退款请求号
        model.setOutRequestNo("HZ01RF001");
        
        // 设置退款包含的商品列表信息
        List<RefundGoodsDetail> refundGoodsDetail = new ArrayList<RefundGoodsDetail>();
        RefundGoodsDetail refundGoodsDetail0 = new RefundGoodsDetail();
        refundGoodsDetail0.setOutSkuId("outSku_01");
        refundGoodsDetail0.setOutItemId("outItem_01");
        refundGoodsDetail0.setGoodsId("apple-01");
        refundGoodsDetail0.setRefundAmount("19.50");
        List<String> outCertificateNoList = new ArrayList<String>();
        outCertificateNoList.add("202407013232143241231243243423");
        refundGoodsDetail0.setOutCertificateNoList(outCertificateNoList);
        refundGoodsDetail.add(refundGoodsDetail0);
        model.setRefundGoodsDetail(refundGoodsDetail);
        
        // 设置退分账明细信息
        List<OpenApiRoyaltyDetailInfoPojo> refundRoyaltyParameters = new ArrayList<OpenApiRoyaltyDetailInfoPojo>();
        OpenApiRoyaltyDetailInfoPojo refundRoyaltyParameters0 = new OpenApiRoyaltyDetailInfoPojo();
        refundRoyaltyParameters0.setAmount("0.1");
        refundRoyaltyParameters0.setTransIn("2088101126708402");
        refundRoyaltyParameters0.setRoyaltyType("transfer");
        refundRoyaltyParameters0.setTransOut("2088101126765726");
        refundRoyaltyParameters0.setTransOutType("userId");
        refundRoyaltyParameters0.setRoyaltyScene("达人佣金");
        refundRoyaltyParameters0.setTransInType("userId");
        refundRoyaltyParameters0.setTransInName("张三");
        refundRoyaltyParameters0.setDesc("分账给2088101126708402");
        refundRoyaltyParameters.add(refundRoyaltyParameters0);
        model.setRefundRoyaltyParameters(refundRoyaltyParameters);
        
        // 设置查询选项
        List<String> queryOptions = new ArrayList<String>();
        queryOptions.add("refund_detail_item_list");
        model.setQueryOptions(queryOptions);
        
        // 设置针对账期交易
        model.setRelatedSettleConfirmNo("2024041122001495000530302869");
        
        request.setBizModel(model);
        // 第三方代调用模式下请设置app_auth_token
        // request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->");

        AlipayTradeRefundResponse response = alipayClient.execute(request);
        System.out.println(response.getBody());

        if (response.isSuccess()) {
            System.out.println("调用成功");
        } else {
            System.out.println("调用失败");
            // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接
            // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response);
            // System.out.println(diagnosisUrl);
        }
    }

    private static AlipayConfig getAlipayConfig() {
        String privateKey  = "<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->";
        String alipayPublicKey = "<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->";
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey(privateKey);
        alipayConfig.setFormat("json");
        alipayConfig.setAlipayPublicKey(alipayPublicKey);
        alipayConfig.setCharset("UTF-8");
        alipayConfig.setSignType("RSA2");
        return alipayConfig;
    }
}
```
<a name="yVeyg"></a>
## 重要入参说明
| **参数英文名** | **描述** |
| --- | --- |
| out_trade_no | 支付时传入的商户订单号，与 trade_no 必填一个。 |
| trade_no | 支付时返回的支付宝交易号，与 out_trade_no 必填一个。 |
| out_request_no | 本次退款请求流水号，部分退款时必传。 |
| refund_amount | 本次退款金额。 |

**说明**：退款接口会根据外部请求号 out_request_no 幂等返回，因此同一笔需要多次部分退款时，必须使用不同的 out_request_no。
<a name="Zxtwu"></a>
## 重要出参说明
| **参数英文名** | **描述** |
| --- | --- |
| refund_fee | 该笔交易已退款的总金额。 |

<a name="tNDu8"></a>
## 退款结果查询

- **退款成功**：退款是否成功可以根据同步响应的 `fund_change` 参数来判断，返回值为 `Y` 则表示退款成功。
- **退款失败**：根据 **错误码** 确认是否要重试，重试时注意 `out_request_no` 需保持一致。
- **系统异常**：无法确认退款结果。
   - 方案一：重试，重试时注意 `out_request_no` 需保持一致。
   - 方案二：先调用 [alipay.trade.fastpay.refund.query](https://ideservice.alipay.com/cms/site/0izhir)（统一收单交易退款查询接口） 确认退款结果，如失败，再发起重试。
<a name="8ifTw"></a>
# 对账流程
目前支付宝对外的常用对账方式有两种：一种是通过在支付宝后台下载账单的方式来对账；一种是通过调用接口的方式来实现对账，下文介绍如何通过接口获取对账单下载链接。更多后台下载及账单示例图详情请可查看对账说明。<br />开发者可通过接口下载指定日期（当天除外）的业务明细账单文件，并结合自身业务系统实现自动对账。
<a name="Tz8bC"></a>
## 调用流程
```
sequenceDiagram
    participant 商户系统
    participant 支付宝

    商户系统->>支付宝: 1: 调用alipay.data.dataservice.bill.downloadurl.query接口
    支付宝-->>商户系统: 1.1: 返回对账单下载地址
    商户系统->>支付宝: 2: 通过HTTP请求对账单下载地址
    支付宝-->>商户系统: 2.1: 获得对账单文件流
    商户系统->>商户系统: 3: 读取文件流处理CSV文件自动对账，或保存至本地
```
**注意**：

- 商家系统调用 [alipay.data.dataservice.bill.downloadurl.query](https://ideservice.alipay.com/cms/site/0izg0k)（查询对账单下载地址接口），传入指定日期，获得该日期账单文件的下载地址。
- 商家系统通过 HTTP 方式后台访问账单下载链接，将账单 CSV 文件下载到本地后自行处理。注意该下载链接仅 30 秒，在得到链接后系统需要立刻下载账单文件。
<a name="FdKBP"></a>
## 请求示例
```java
package com.java.sdk.demo;

import com.alipay.api.AlipayApiException;
import com.alipay.api.AlipayClient;
import com.alipay.api.DefaultAlipayClient;
import com.alipay.api.AlipayConfig;
import com.alipay.api.request.AlipayDataDataserviceBillDownloadurlQueryRequest;
import com.alipay.api.response.AlipayDataDataserviceBillDownloadurlQueryResponse;
import com.alipay.api.domain.AlipayDataDataserviceBillDownloadurlQueryModel;

import com.alipay.api.FileItem;
import java.util.Base64;
import java.util.ArrayList;
import java.util.List;

public class AlipayDataDataserviceBillDownloadurlQuery {

    public static void main(String[] args) throws AlipayApiException {
        // 初始化SDK
        AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig());

        // 构造请求参数以调用接口
        AlipayDataDataserviceBillDownloadurlQueryRequest request = new AlipayDataDataserviceBillDownloadurlQueryRequest();
        AlipayDataDataserviceBillDownloadurlQueryModel model = new AlipayDataDataserviceBillDownloadurlQueryModel();
        
        // 设置账单类型
        model.setBillType("trade");
        
        // 设置账单时间
        model.setBillDate("2025-05-01");
        
        // 设置二级商户smid
        model.setSmid("2088123412341234");
        
        request.setBizModel(model);
        // 第三方代调用模式下请设置app_auth_token
        // request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->");

        AlipayDataDataserviceBillDownloadurlQueryResponse response = alipayClient.execute(request);
        System.out.println(response.getBody());

        if (response.isSuccess()) {
            System.out.println("调用成功");
        } else {
            System.out.println("调用失败");
            // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接
            // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response);
            // System.out.println(diagnosisUrl);
        }
    }

    private static AlipayConfig getAlipayConfig() {
        String privateKey  = "<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->";
        String alipayPublicKey = "<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->";
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey(privateKey);
        alipayConfig.setFormat("json");
        alipayConfig.setAlipayPublicKey(alipayPublicKey);
        alipayConfig.setCharset("UTF-8");
        alipayConfig.setSignType("RSA2");
        return alipayConfig;
    }
}
```
<a name="GGKzH"></a>
## 响应示例
```json
{
    "sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE",
    "alipay_data_dataservice_bill_downloadurl_query_response":{
        "msg":"Success",
        "code":"10000",
        "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"
    }
}
```
<a name="rQKRY"></a>
## 重要出参说明
| **参数英文名** | **描述** |
| --- | --- |
| bill_download_url | 对账单下载地址，下载地址有效时间为 30 秒，请尽快下载。 |