## 接口说明

接口名称：`alipay.trade.query`

该接口提供所有支付宝支付订单的查询。商户可以通过该接口主动查询订单状态，并据此完成下一步业务逻辑。

## 适用场景

需要调用查询接口的常见情况：

- 商户后台、网络、服务器等出现异常，商户系统最终未接收到支付通知。
- 调用支付接口后，返回系统错误或未知交易状态。
- 调用 `alipay.trade.cancel` 前，需要先确认支付状态。

## 公共请求参数

| 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 |
| --- | --- | --- | --- | --- | --- |
| `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用 ID | `2014072300007148` |
| `method` | String | 必选 | 128 | 接口名称 | `alipay.trade.query` |
| `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 | 商户请求参数的签名串，详见[签名](https://ideservice.alipay.com/cms/site/02khjm) | 详见示例 |
| `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 | 详见[应用授权概述](https://ideservice.alipay.com/cms/site/04h2nx) | - |
| `biz_content` | String | 必选 | - | 请求参数集合。除公共参数外，所有请求参数都必须放在该参数中传递，具体参照各产品快速接入文档 | - |

## 业务请求参数

> `out_trade_no` 与 `trade_no` 二选一传入，不能同时为空。若 `trade_no` 与 `out_trade_no` 同时存在，优先使用 `trade_no` 查询。

| 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 枚举值/说明 | 示例值 |
| --- | --- | --- | --- | --- | --- | --- |
| `out_trade_no` | string | 二选一 | 64 | 订单支付时传入的商户订单号，和支付宝交易号不能同时为空 | 若与 `trade_no` 同时存在，优先取 `trade_no` | `20150320010101001` |
| `trade_no` | string | 二选一 | 64 | 支付宝交易号，和商户订单号不能同时为空 | 若与 `out_trade_no` 同时存在，优先取 `trade_no` | `2014112611001004680 073956707` |

## 常见请求示例

::::aipay-tabs{defaultActiveKey="Java"}
:::aipay-tab{key="cURL" title="cURL"}
```bash
curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.query&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2&timestamp=${now}' \
 -F 'app_auth_token=${app_auth_token}' \
 -F 'biz_content={
	"out_trade_no":"20150320010101001",
	"trade_no":"2014112611001004680 073956707",
	"query_options":[
		"trade_settle_info"
	]
}'
```
:::

:::aipay-tab{key="Java" title="Java"}
```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");
        
        // 设置查询选项
        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;
    }
}
```
:::

:::aipay-tab{key="C#" title="C#"}
```csharp
using System;
using System.Collections.Generic;
using Aop.Api;
using Aop.Api.Request;
using Aop.Api.Response;
using Aop.Api.Domain;
using Aop.Api.Util;
namespace SdkDemoTest
{
    public class AlipayTradeQuery
    {
        public static void Main(string[] args) 
        {
            // 初始化SDK
            IAopClient alipayClient = new DefaultAopClient(GetAlipayConfig());
            // 构造请求参数以调用接口
            AlipayTradeQueryRequest request = new AlipayTradeQueryRequest();
            AlipayTradeQueryModel model = new AlipayTradeQueryModel();
            
            // 设置订单支付时传入的商户订单号
            model.OutTradeNo = "20150320010101001";
            
            // 设置支付宝交易号
            model.TradeNo = "2014112611001004680 073956707";
            
            // 设置查询选项
            List<String> queryOptions = new List<String>();
            queryOptions.Add("trade_settle_info");
            model.QueryOptions = queryOptions;
            
            request.SetBizModel(model);
            // 第三方代调用模式下请设置app_auth_token
            // request.PutOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->");

            AlipayTradeQueryResponse response = alipayClient.Execute(request);

            if(!response.IsError)
            {
                Console.WriteLine("调用成功");
            }
            else
            {
                Console.WriteLine("调用失败");
            }
        }

        private static AlipayConfig GetAlipayConfig()
        {
            string privateKey  = "<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->";
            string alipayPublicKey = "<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->";
            AlipayConfig alipayConfig = new AlipayConfig();
            alipayConfig.ServerUrl = "https://openapi.alipay.com/gateway.do";
            alipayConfig.AppId = "<-- 请填写您的AppId，例如：2019091767145019 -->";
            alipayConfig.PrivateKey = privateKey;
            alipayConfig.Format = "json";
            alipayConfig.AlipayPublicKey = alipayPublicKey;
            alipayConfig.Charset = "UTF-8";
            alipayConfig.SignType = "RSA2";
            return alipayConfig;
        }
    }
}
```
:::

:::aipay-tab{key="PHP" title="PHP"}
```php
<?php
require_once '../aop/AopClient.php';
require_once '../aop/AopCertClient.php';
require_once '../aop/AopCertification.php';
require_once '../aop/AlipayConfig.php';
require_once '../aop/request/AlipayTradeQueryRequest.php';

// 初始化SDK
$alipayClient = new AopClient(getAlipayConfig());
// 构造请求参数以调用接口
$request = new AlipayTradeQueryRequest();
$model = array();

// 设置订单支付时传入的商户订单号
$model['out_trade_no'] = "20150320010101001";

// 设置支付宝交易号
$model['trade_no'] = "2014112611001004680 073956707";

// 设置查询选项
$queryOptions = array();
$queryOptions[] = "trade_settle_info";
$model['query_options'] = $queryOptions;

$request->setBizContent(json_encode($model,JSON_UNESCAPED_UNICODE));
// 如果是第三方代调用模式，请设置app_auth_token（应用授权令牌）
$responseResult = $alipayClient->execute($request, null, "<-- 请填写应用授权令牌 -->", null);
$responseApiName = str_replace(".","_",$request->getApiMethodName())."_response";
$response = $responseResult->$responseApiName;
if(!empty($response->code)&&$response->code==10000){
    echo("调用成功");
}
else{
    echo("调用失败");
}

function getAlipayConfig()
{
    $privateKey  = '<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->';
    $alipayPublicKey = '<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->';
    $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;
}
```
:::

:::aipay-tab{key="Node.js" title="Node.js"}
```javascript
const { AlipaySdk } = require("alipay-sdk");

const alipaySdk = new AlipaySdk({
  appId: "<-- 请填写您的AppId，例如：2019091767145019 -->",
  privateKey: "<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->",
  alipayPublicKey: "<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->",
  gateway: "https://openapi.alipay.com/gateway.do",
  appAuthToken: "<-- 请填写应用授权令牌 -->",
});
const result = await alipaySdk.exec("alipay.trade.query", {
  bizContent: {
    out_trade_no: "20150320010101001",
    trade_no: "2014112611001004680+073956707",
    query_options: ["trade_settle_info"],
  },
});
```
:::

::::

## 公共响应参数

| 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 |
| --- | --- | --- | --- | --- | --- |
| `code` | String | 必选 | - | 网关返回码，详见[公共错误码](https://ideservice.alipay.com/cms/site/02km9f) | `40004` |
| `msg` | String | 必选 | - | 网关返回码描述，详见[公共错误码](https://ideservice.alipay.com/cms/site/02km9f) | `Business Failed` |
| `sub_code` | String | 可选 | - | 业务返回码，参见具体 API 接口文档 | `ACQ.TRADE_HAS_SUCCESS` |
| `sub_msg` | String | 可选 | - | 业务返回码描述，参见具体 API 接口文档 | `交易已被支付` |
| `sign` | String | 必选 | - | 签名，详见[签名文档](https://ideservice.alipay.com/cms/site/02kf5q) | `DZXh8eeTuAHoYE3w1J+POiPh...` |

## 业务响应参数

| 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 |
| --- | --- | --- | --- | --- | --- | --- |
| `trade_no` | string | 必选 | 64 | 支付宝交易号 | 在未生成真实交易时不返回，需要商户多次调用该接口或等待支付通知，获取最终的交易号 | `2013112011001004330000121536` |
| `out_trade_no` | string | 必选 | 64 | 商家订单号 | - | `6823789339978248` |
| `trade_status` | string | 必选 | 32 | 交易状态 | `WAIT_BUYER_PAY`：交易创建，等待买家付款<br>`TRADE_CLOSED`：未付款交易超时关闭，或支付完成后全额退款<br>`TRADE_SUCCESS`：交易支付成功<br>`TRADE_FINISHED`：交易结束，不可退款 | `TRADE_CLOSED` |
| `total_amount` | price | 必选 | 11 | 交易的订单金额，单位为元，两位小数 | 该参数的值为支付时传入的 `total_amount` | `88.88` |
| `buyer_user_id` | string | 必选 | 16 | 买家在支付宝的用户 ID | 新商户建议使用 `buyer_open_id` 替代该字段。对于新商户，`buyer_user_id` 字段未来计划逐步回收，存量商户可继续使用。若使用 `buyer_open_id`，请确认“应用 - 开发配置 - openid 配置管理”已启用；无该配置项时，可查看 [openid 配置申请](https://ideservice.alipay.com/cms/site/0ai9ok?pathHash=de631c06) | `2088101117955611` |
| `send_pay_date` | date | 特殊可选 | 32 | 本次交易打款给卖家的时间 | - | `2014-11-27 15:45:57` |
| `receipt_amount` | string | 特殊可选 | 11 | 实收金额，单位为元，两位小数 | 该金额为本笔交易中商户账户能够实际收到的金额 | `15.25` |
| `buyer_open_id` | string | 特殊可选 | 128 | 买家支付宝用户唯一标识 | 详情可查看 [openid 简介](https://ideservice.alipay.com/cms/site/0ai2i6?pathHash=13dd5946) | `01501o8f93I3nJAGB1jG4ONxtxV25DCN3Gec3uggnC4CJU0` |
| `buyer_logon_id` | string | 可选 | 100 | 买家支付宝账号 | 在未生成真实交易时不返回，需要商户多次调用该接口或等待支付通知，获取最终的用户信息 | `159****5620` |

## 响应示例

::::aipay-tabs{defaultActiveKey="正常示例"}
:::aipay-tab{key="正常示例" title="正常示例"}
```json
{
  "alipay_trade_query_response": {
    "code": "10000",
    "msg": "Success",
    "trade_no": "2013112011001004330000121536",
    "out_trade_no": "6823789339978248",
    "buyer_logon_id": "159****5620",
    "trade_status": "TRADE_CLOSED",
    "total_amount": "88.88",
    "send_pay_date": "2014-11-27 15:45:57",
    "buyer_pay_amount": "8.88",
    "invoice_amount": "12.11",
    "point_amount": "10",
    "receipt_amount": "15.25",
    "store_id": "NJ_S_001",
    "terminal_id": "NJ_T_001",
    "fund_bill_list": [
      {
        "fund_channel": "ALIPAYACCOUNT",
        "amount": "10",
        "real_amount": "11.21"
      }
    ],
    "store_name": "证大五道口店",
    "buyer_open_id": "01501o8f93I3nJAGB1jG4ONxtxV25DCN3Gec3uggnC4CJU0",
    "buyer_user_id": "2088101117955611",
    "discount_amount": "88.88",
    "ext_infos": "{\"action\":\"cancel\"}",
    "buyer_user_type": "PRIVATE",
    "mdiscount_amount": "88.88"
  },
  "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}
```
:::

:::aipay-tab{key="异常示例" title="异常示例"}
```json
{
  "alipay_trade_query_response": {
    "code": "20000",
    "msg": "Service Currently Unavailable",
    "sub_code": "isp.unknow-error",
    "sub_msg": "系统繁忙"
  },
  "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}
```
:::

::::


## 公共错误码

[前往查看公共错误码](https://ideservice.alipay.com/cms/site/02km9f)

## 业务错误码

| 错误码 | 错误描述 | 解决方案 |
| --- | --- | --- |
| `ACQ.INVALID_PARAMETER` | 参数无效 | 检查请求参数，修改后重新发起请求 |
| `ACQ.SYSTEM_ERROR` | 系统错误 | 重新发起请求 |
| `ACQ.TRADE_NOT_EXIST` | 查询的交易不存在 | 检查传入的交易号是否正确，修改后重新发起请求 |