alipay.trade.query 未返回字段，如何配置接口入参？

2026-10-24支付老李

结论

alipay.trade.query 不能通过入参任意指定返回字段。接口定义中的扩展信息需要通过 query_options 选择；普通响应字段由支付宝根据交易状态、支付方式和实际业务数据返回，无法通过配置入参强制生成。

如果目标字段不在 query_options 的支持范围内，需要确认该字段是否属于当前接口的响应模型，以及这笔交易是否产生了相应数据。

入参配置

调用接口时，必须提供支付宝交易号 trade_no 或商户订单号 out_trade_no。如果需要查询资金渠道、结算信息或优惠券明细，可以传入对应的 query_options。

常见查询选项有：

trade_settle_info：查询交易结算信息。
fund_bill_list：查询支付资金渠道信息。
voucher_detail_list：查询优惠券明细。
discount_goods_detail：查询单品优惠信息。

支持哪些选项，应以当前接入版本的支付宝开放平台接口文档为准。产品权限或接口版本不同，可用选项也可能不同。

请求业务参数示例：

{
  "out_trade_no": "ORDER_202609090001",
  "query_options": [
    "trade_settle_info",
    "fund_bill_list",
    "voucher_detail_list",
    "discount_goods_detail"
  ]
}

如果已经取得支付宝交易号，建议使用 trade_no 查询：

{
  "trade_no": "2026090922001000000000000000",
  "query_options": [
    "fund_bill_list"
  ]
}

Java SDK 示例

不同版本 SDK 的类名和方法可能略有差异，常见写法如下：

AlipayTradeQueryRequest request = new AlipayTradeQueryRequest();

AlipayTradeQueryModel model = new AlipayTradeQueryModel();
model.setOutTradeNo("ORDER_202609090001");
model.setQueryOptions(Arrays.asList(
    "trade_settle_info",
    "fund_bill_list",
    "voucher_detail_list"
));

request.setBizModel(model);

AlipayTradeQueryResponse response = alipayClient.execute(request);

if (response.isSuccess()) {
    System.out.println(response.getBody());
} else {
    System.out.println(response.getCode());
    System.out.println(response.getSubCode());
    System.out.println(response.getSubMsg());
}

如果当前 SDK 的模型没有 setQueryOptions 方法，可以改用 JSON 设置 biz_content，也可以升级到支持该参数的 SDK 版本：

AlipayTradeQueryRequest request = new AlipayTradeQueryRequest();

request.setBizContent("""
{
  "out_trade_no": "ORDER_202609090001",
  "query_options": [
    "fund_bill_list",
    "voucher_detail_list"
  ]
}
""");

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

字段仍未返回时的排查方法

1. 确认字段是否需要 `query_options`

先查看接口文档对目标字段的说明。资金渠道、结算、优惠券或单品优惠等扩展结构，需要传入对应的查询选项。

交易状态、买家信息、金额等普通响应字段，通常不受 query_options 控制。

2. 确认交易是否存在对应数据

传入查询选项，只表示请求返回相关信息，不保证字段一定会出现。例如：

交易未使用优惠券时，可能没有优惠券明细。
交易没有分账、补差等结算数据时，可能没有相应的结算信息。
交易尚未支付时，通常不会产生完整的资金渠道数据。
部分字段只会在特定支付产品、交易状态或签约权限下返回。

因此，字段为空或缺失不一定是请求配置错误。

3. 检查实际发送的请求

除了检查业务代码中的对象，还要查看最终发给支付宝的 biz_content，确认其中确实包含 query_options，并且参数采用 JSON 数组格式：

"query_options": [
  "fund_bill_list"
]

不能写成普通字符串：

"query_options": "fund_bill_list"

4. 检查响应原文

部分 SDK 的响应对象可能尚未映射新增字段，但原始响应报文中已经包含这些字段。排查时应同时查看：

response.getBody()

如果原始 JSON 中有字段，而 SDK 对象没有对应属性，通常是 SDK 模型版本或反序列化问题。此时可以升级 SDK，或直接解析原始响应。

注意事项

query_options 只能启用接口已经支持的扩展返回项，不能填写任意响应字段名。
枚举值的大小写、拼写和可用范围，应以当前接口文档为准。
不要为了获取更多字段而传入未经文档确认的枚举值，否则可能触发参数校验失败。
查询成功只表示系统找到了交易并正常返回，不代表每个可选字段都有业务数据。
如果目标字段不在 alipay.trade.query 的响应定义中，需要改用相应的账单、结算、退款或其他专用接口查询。增加查询入参不能让该接口返回定义之外的字段。