商品权益购买结果查询接口
最后更新于
接口说明
接口名称:alipay.aipay.nowpay.purchase.query
查询即刻收平台商品购买结果。通过外部商品标识、平台商品所有者标识和平台买家标识定位查询范围,并可使用创建购买链接时的请求幂等号、购买链接标识及指定档位查询对应购买结果。
适用场景
- 买家完成购买流程后,查询商品购买结果。
- 额度包购买后,使用原请求幂等号或购买链接标识查询对应订单结果。
- 创建购买链接时指定了档位,携带该档位标识查询购买结果。
注意事项
out_product_id、external_owner_id、external_buyer_id为必选字段,需与实际商品及买家对应。- 额度包查询必须传入
out_request_no或purchase_link_id,否则返回ILLEGAL_PARAMETERS。 - 额度包场景尽量传入创建购买链接时的
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.nowpay.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 | 商户请求参数的签名串,详见签名 | 详见示例 |
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 | 已获授权的第三方代调用场景使用的应用授权令牌,详见应用授权概述 | - |
biz_content |
String | 必选 | - | 业务请求参数的 JSON 字符串,字段使用 snake_case;详见下表 | - |
业务请求参数
业务字段统一放入 biz_content。下表数组子字段使用 [] 表示元素路径。
| 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 |
|---|---|---|---|---|---|---|
out_product_id |
String | 必选 | 128 | 外部商品标识 | - | app_1029001 |
external_owner_id |
String | 必选 | 128 | 平台商品所有者标识 | - | owner_10001 |
external_buyer_id |
String | 必选 | 128 | 平台买家标识 | - | buyer_10001 |
out_request_no |
String | 可选 | 64 | purchase.create 创建购买链接时传入的请求幂等号 |
额度包查询必须传入本字段或 purchase_link_id;尽量传入本字段,否则超过半小时的订单无法查询结果 |
1c4c07f08f4f41a89615c1f2e212d3e0 |
purchase_link_id |
String | 可选 | 128 | purchase.create / purchase.consult 响应中的购买链接标识 |
额度包查询必须传入本字段或 out_request_no |
Tk9XUEFZOlBVUkNIQVNFOjgyNzQ2Y2M2MWNkMDRmNGJhYTViNDZmYTIyMzVhNjE4XyQ3MA |
sku_id |
String | 可选 | 32 | 指定档位标识 | 创建购买链接时若指定档位,查询时需传入 | S0806000200864400 |
常见请求示例
以下商品、所有者、买家、请求号及购买链接标识均为演示值。Java 使用支付宝服务端 SDK;私钥保存在平台服务端。cURL 签名需基于本次实际请求生成,授权令牌按实际调用场景配置。
biz_content='{
"out_product_id": "app_1029001",
"external_owner_id": "owner_10001",
"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.nowpay.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}"import com.alipay.api.AlipayConfig;
import com.alipay.api.AlipayClient;
import com.alipay.api.DefaultAlipayClient;
import com.alipay.api.request.AlipayAipayNowpayPurchaseQueryRequest;
import com.alipay.api.response.AlipayAipayNowpayPurchaseQueryResponse;
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);
AlipayAipayNowpayPurchaseQueryRequest request = new AlipayAipayNowpayPurchaseQueryRequest();
request.setBizContent("{\"out_product_id\":\"app_1029001\",\"external_owner_id\":\"owner_10001\",\"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);
}
AlipayAipayNowpayPurchaseQueryResponse 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_nowpay_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:参数不全,无法确认购买结果;补充原请求幂等号、购买链接标识或所需档位后查询,不按购买成功处理。- 返回
ILLEGAL_PARAMETERS:额度包查询补充out_request_no或purchase_link_id后重试。 - 返回
NOW_PAY_BINDING_INVALID:核对外部商品标识及平台商品所有者标识。 - 返回
NOW_PAY_NO_PERMISSION:核对订单是否属于当前平台买家,不按购买成功处理。 - 返回
SYSTEM_ERROR:可使用同样的业务参数重试;重新发送时按实际请求生成签名。
响应示例
{
"purchase_status": "SUCCESS",
"trade_no": "2026100122001431111104111324"
}{
"alipay_aipay_nowpay_purchase_query_response": {
"code": "20000",
"msg": "Service Currently Unavailable",
"sub_code": "isp.unknow-error",
"sub_msg": "系统繁忙"
},
"sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}公共错误码
参见支付宝公共错误码。网关或系统异常时,按原请求查询或重试;写操作不能在结果未确认时更换幂等号。
业务错误码
| 错误码 | 错误描述 | 解决方案 |
|---|---|---|
SYSTEM_ERROR |
系统繁忙 | 服务器异常,可能发生了网络或者系统异常,导致服务调用失败;商户可以用同样的请求发起重试 |
INVALID_PARAMETER |
参数有误 | 根据接口返回的参数非法的具体错误信息,修改参数后重试 |
ILLEGAL_PARAMETERS |
缺少必要参数:out_request_no 或 purchase_link_id |
额度包查询必须传入 out_request_no 或 purchase_link_id |
NOW_PAY_BINDING_INVALID |
商品不存在或商品标识与所有者不匹配 | 商品不存在,请核对商品标识和所有者标识 |
NOW_PAY_NO_PERMISSION |
订单归属越权 | 所查订单不属于当前平台买家,请核对买家标识及订单归属 |