Alipay SDK for PHP 找不到分账剩余金额查询接口

2026-10-24支付小周

结论

AlipayTradeOrderOnsettleQueryRequest 是支付宝开放平台接口 alipay.trade.order.onsettle.query 在传统 PHP AOP SDK 中对应的请求类，扩展通常不会修改这个名称。

如果代码中找不到该类，常见原因有：

当前安装的 SDK 版本较旧，还没有生成这个接口类；
项目使用的是 Easy SDK、OpenAPI SDK 或第三方框架扩展，而不是传统 AOP SDK；
扩展只封装了部分支付接口，没有提供分账剩余金额查询；
类文件已经存在，但 Composer 自动加载或命名空间的使用方式不正确。

onsettle 是接口名称的一部分，不要自行改成 unsettle、onSettle 等其他拼写。

先确认正在使用哪套 SDK

先通过 Composer 查看项目实际安装了哪些支付宝相关包：

composer show | grep -i alipay

再到项目依赖中搜索请求类和接口名：

grep -R "AlipayTradeOrderOnsettleQueryRequest" vendor/
grep -R "alipay.trade.order.onsettle.query" vendor/

如果两项搜索都没有结果，通常不是类名写错，而是当前 SDK 不包含该接口。此时需要升级正在使用的 SDK，或者从支付宝开放平台下载包含该接口的新版 PHP SDK。

升级前要先核对项目的依赖约束和兼容性，不建议直接替换生产环境中的 SDK。

传统 AOP SDK 的调用方式

如果传统 PHP AOP SDK 中包含这个请求类，可以这样调用：

<?php

$request = new AlipayTradeOrderOnsettleQueryRequest();

$request->setBizContent(json_encode([
    'trade_no' => '2026xxxxxxxxxxxxxxxx',
], JSON_UNESCAPED_UNICODE));

$result = $aopClient->execute($request);

$responseKey = str_replace(
    '.',
    '_',
    $request->getApiMethodName()
) . '_response';

$response = $result->{$responseKey} ?? null;

if ($response === null) {
    throw new RuntimeException('支付宝返回中缺少预期的响应节点');
}

if (($response->code ?? null) !== '10000') {
    throw new RuntimeException(sprintf(
        '查询失败：code=%s，sub_code=%s，sub_msg=%s',
        $response->code ?? '',
        $response->sub_code ?? '',
        $response->sub_msg ?? ''
    ));
}

var_dump($response);

示例中的 $aopClient 需要预先配置 appId、应用私钥、支付宝公钥、网关地址和签名算法等参数。返回字段应以当前开放平台接口文档和实际 SDK 模型为准。

如果 SDK 使用了命名空间，还要根据包内的类声明正确导入，例如：

use AlipayTradeOrderOnsettleQueryRequest;

传统 AOP SDK 的部分发行版本没有统一的命名空间，因此不要凭经验添加 Alipay\Request\... 之类的前缀。具体写法要以类文件中的 namespace 声明为准。

使用框架扩展时怎么处理

Laravel、ThinkPHP 等第三方扩展通常只提供统一入口，例如：

$alipay->query(...);

这类 query() 查询的往往是交易状态，并不等同于 alipay.trade.order.onsettle.query。扩展是否支持分账剩余金额查询，要查看它的接口映射或底层请求能力。

如果扩展允许获取原始 AopClient，可以跳过上层封装，直接执行 AlipayTradeOrderOnsettleQueryRequest。如果底层依赖中也没有这个类，就需要升级依赖，或者为扩展补充相应的请求类和调用封装。只修改类名无法解决问题。

类存在但仍提示找不到

如果类文件已经存在，可以重新生成 Composer 自动加载文件：

composer dump-autoload

同时检查以下几项：

PHP 文件名与类名的大小写是否完全一致；
项目是否加载了正确的 vendor/autoload.php；
服务器是否还在使用旧的发布目录或依赖缓存；
项目中是否同时安装了多套支付宝 SDK；
请求类是否声明了命名空间。

注意事项

该接口查询的是订单中可继续分账的相关金额，不是普通的支付宝账户余额。调用前还要确认应用已经具备对应的产品能力和接口权限。

交易号应使用支付宝交易号 trade_no。在没有核对当前接口文档前，不要用商户订单号 out_trade_no 替代。即使请求类能够正常实例化，如果接口权限未开通、交易不支持分账，或者交易状态不符合要求，仍可能收到业务错误。

处理响应时，要同时检查 code、sub_code 和 sub_msg，不能只判断 HTTP 请求是否成功。