﻿
## 接口说明

接口名称：`alipay.aipay.nowpaydirect.purchase.query`

查询直连模式下的权益购买结果。通过外部商品标识和平台买家标识定位查询范围，并可使用创建购买链接时的请求幂等号、购买链接标识及指定档位查询对应购买结果。

## 适用场景

- 买家完成购买流程后，查询商品购买结果。
- 额度包购买后，使用原请求幂等号或购买链接标识查询对应订单结果。
- 创建购买链接时指定了档位，携带该档位标识查询购买结果。

## 注意事项

- `out_product_id`、`external_buyer_id` 为必选字段，需与实际商品及买家对应。
- 额度包场景尽量传入创建购买链接时的 `out_request_no`；原文提示，不传时超过半小时的订单无法查询结果。
- `purchase_link_id` 使用 `purchase.create` 或 `purchase.consult` 返回的购买链接标识，按原值保存和传入。
- `purchase.create` 创建购买链接时若指定了档位，查询时需传入对应的 `sku_id`。
- 原文枚举说明存在错列，将 `SUCCESS`、`WAIT_PAY` 分别与商品类型并列展示。本文保留状态值；状态与商品类型的对应关系需在接入时核对。

## 公共请求参数

| 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 |
| --- | --- | --- | --- | --- | --- |
| `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用ID | `YOUR_APP_ID` |
| `method` | String | 必选 | 128 | 接口名称 | `alipay.aipay.nowpaydirect.purchase.query` |
| `format` | String | 可选 | 40 | 仅支持JSON | `JSON` |
| `charset` | String | 必选 | 10 | 请求使用的编码格式，如utf-8,gbk,gb2312等 | `utf-8` |
| `sign_type` | String | 必选 | 10 | 请求签名算法，推荐 RSA2 | `RSA2` |
| `sign` | String | 必选 | 344 | 商户请求参数的签名串，详见[签名](https://opendocs.alipay.com/common/02khjm) | `详见示例` |
| `timestamp` | String | 必选 | 19 | 发送请求的时间，格式"yyyy-MM-dd HH:mm:ss" | `2026-09-07 10:00:00` |
| `version` | String | 必选 | 3 | 调用的接口版本，固定为：1.0 | `1.0` |
| `app_auth_token` | String | 可选 | 40 | 已获授权的第三方代调用场景使用的应用授权令牌，详见[应用授权概述](https://opendocs.alipay.com/isv/10467/xldcyq) | - |
| `biz_content` | String | 必选 | - | 业务请求参数的 JSON 字符串，字段使用 snake_case；详见下表 | - |

## 业务请求参数

业务字段统一放入 `biz_content`。下表数组子字段使用 `[]` 表示元素路径。

| 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 |
| --- | --- | --- | --- | --- | --- | --- |
| `out_product_id` | String | 必选 | 128 | 外部商品标识 | - | `app_1029001` |
| `external_buyer_id` | String | 必选 | 128 | 平台买家标识 | - | `buyer_10001` |
| `out_request_no` | String | 可选 | 64 | `purchase.create` 创建购买链接时传入的请求幂等号 | 额度包场景尽量传入，否则超过半小时的订单无法查询结果 | 1c4c07f08f4f41a8<br>9615c1f2e212d3e0 |
| `purchase_link_id` | String | 可选 | 128 | `purchase.create` / `purchase.consult` 响应中的购买链接标识 | - | Tk9XUEFZOlBVUkNIQVNFOjgy<br>NzQ2Y2M2MWNkMDRmNGJhYTVi<br>NDZmYTIyMzVhNjE4XyQ3MA |
| `sku_id` | String | 可选 | 32 | 指定档位标识 | 创建购买链接时若指定档位，查询时需传入 | `S0806000200864400` |
## 常见请求示例

以下商品、买家、请求号及购买链接标识均为演示值。Java 使用支付宝服务端 SDK；私钥保存在平台服务端。cURL 签名需基于本次实际请求生成，授权令牌按实际调用场景配置。

::::aipay-tabs{defaultActiveKey="cURL"}

:::aipay-tab{key="cURL" title="cURL"}
```bash
biz_content='{
  "out_product_id": "app_1029001",
  "external_buyer_id": "buyer_10001",
  "out_request_no": "1c4c07f08f4f41a89615c1f2e212d3e0",
  "purchase_link_id": "Tk9XUEFZOlBVUkNIQVNFOjgyNzQ2Y2M2MWNkMDRmNGJhYTViNDZmYTIyMzVhNjE4XyQ3MA",
  "sku_id": "S0806000200864400"
}'

# app_id、timestamp、sign 由平台准备；sign 必须基于本次完整参数生成。
curl --request POST 'https://openapi.alipay.com/gateway.do' \
  --data-urlencode "app_id=${app_id}" \
  --data-urlencode 'method=alipay.aipay.nowpaydirect.purchase.query' \
  --data-urlencode 'format=json' \
  --data-urlencode 'charset=UTF-8' \
  --data-urlencode 'sign_type=RSA2' \
  --data-urlencode "timestamp=${timestamp}" \
  --data-urlencode 'version=1.0' \
  --data-urlencode "biz_content=${biz_content}" \
  --data-urlencode "sign=${sign}"
```
:::

:::aipay-tab{key="Java" title="Java"}
```java
import com.alipay.api.AlipayConfig;
import com.alipay.api.AlipayClient;
import com.alipay.api.DefaultAlipayClient;
import com.alipay.api.request.AlipayAipayNowpaydirectPurchaseQueryRequest;
import com.alipay.api.response.AlipayAipayNowpaydirectPurchaseQueryResponse;

public class NowpayExample {
    public static void main(String[] args) throws Exception {
        AlipayConfig config = new AlipayConfig();
        config.setServerUrl("https://openapi.alipay.com/gateway.do");
        config.setAppId(System.getenv("ALIPAY_APP_ID"));
        config.setPrivateKey(System.getenv("ALIPAY_PRIVATE_KEY"));
        config.setAlipayPublicKey(System.getenv("ALIPAY_PUBLIC_KEY"));
        config.setFormat("json");
        config.setCharset("UTF-8");
        config.setSignType("RSA2");
        AlipayClient client = new DefaultAlipayClient(config);

        AlipayAipayNowpaydirectPurchaseQueryRequest request = new AlipayAipayNowpaydirectPurchaseQueryRequest();
        request.setBizContent("{\"out_product_id\":\"app_1029001\",\"external_buyer_id\":\"buyer_10001\",\"out_request_no\":\"1c4c07f08f4f41a89615c1f2e212d3e0\",\"purchase_link_id\":\"Tk9XUEFZOlBVUkNIQVNFOjgyNzQ2Y2M2MWNkMDRmNGJhYTViNDZmYTIyMzVhNjE4XyQ3MA\",\"sku_id\":\"S0806000200864400\"}");
        // 仅在已获授权的第三方代调用场景设置 app_auth_token。
        String appAuthToken = System.getenv("ALIPAY_APP_AUTH_TOKEN");
        if (appAuthToken != null && !appAuthToken.isEmpty()) {
            request.putOtherTextParam("app_auth_token", appAuthToken);
        }
        AlipayAipayNowpaydirectPurchaseQueryResponse response = client.execute(request);
        if (!response.isSuccess()) {
            // 按 code/sub_code 处理；结果未知时保留原业务请求号。
            System.out.println(response.getCode() + ":" + response.getSubCode());
            return;
        }
        // 网关成功后，按本页“结果处理”读取业务字段。
        System.out.println(response.getBody());
    }
}
```
:::

::::

## 公共响应参数

| 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 |
| --- | --- | --- | --- | --- | --- |
| `code` | String | 必选 | - | 网关返回码；10000 表示接口调用成功 | `10000` |
| `msg` | String | 必选 | - | 网关返回码说明 | `Success` |
| `sub_code` | String | 可选 | - | 业务错误码；仅用于接口失败处理 | - |
| `sub_msg` | String | 可选 | - | 业务错误说明；不用于编写固定业务分支 | - |
| `sign` | String | 必选 | - | 响应签名，位于响应根对象；由 SDK 按配置验签 | - |

响应业务对象名为 `alipay_aipay_nowpaydirect_purchase_query_response`。先完成验签并判断 `code`，再读取业务结果。

## 业务响应参数

| 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 |
| --- | --- | --- | --- | --- | --- | --- |
| `purchase_status` | String | 必选 | 32 | 购买结果 | `SUCCESS` / `WAIT_PAY` / `UNKNOWN`；`UNKNOWN` 表示参数不全，无法确认 | `SUCCESS` |
| `trade_no` | String | 可选 | 64 | 支付宝订单号 | 按实际返回读取 | `2026100122001431111104111324` |

## 结果处理

- `purchase_status` 为 `SUCCESS`：按购买成功处理，并记录返回的支付宝订单号。
- `purchase_status` 为 `WAIT_PAY`：按待支付处理，可在买家完成支付后再次查询。
- `purchase_status` 为 `UNKNOWN`：参数不全，无法确认购买结果；补充原请求幂等号、购买链接标识或所需档位后查询，不按购买成功处理。
- 返回 `SYSTEM_ERROR`：可使用同样的业务参数重试；重新发送时按实际请求生成签名。

## 响应示例

::::aipay-tabs{defaultActiveKey="正常示例"}

:::aipay-tab{key="正常示例" title="正常示例"}
```json
{
  "purchase_status": "SUCCESS",
  "trade_no": "2026100122001431111104111324"
}
```
:::

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

::::

## 公共错误码

参见[支付宝公共错误码](https://opendoc.alipay.com/common/02km9f)。网关或系统异常时，按原请求查询或重试；写操作不能在结果未确认时更换幂等号。

## 业务错误码

| 错误码 | 错误描述 | 解决方案 |
| --- | --- | --- |
| `SYSTEM_ERROR` | 系统繁忙 | 服务器异常，可能发生了网络或者系统异常，导致服务调用失败；商户可以用同样的请求发起重试 |
| `INVALID_PARAMETER` | 参数有误 | 根据接口返回的参数非法的具体错误信息，修改参数后重试 |
