支付宝支付交易投诉接口文档及异步通知订阅方式

2026-10-24支付老李

结论

“支付交易投诉”不需要使用另一套独立的查询接口。开通对应的投诉处理能力后，仍通过以下接口查询和处理投诉：

alipay.merchant.tradecomplain.batchquery：查询交易投诉列表
alipay.merchant.tradecomplain.query：查询投诉详情
alipay.merchant.tradecomplain.reply：回复投诉
其他处理接口以支付宝开放平台当前展示的“交易投诉处理”接口列表为准

如果需要实时接收支付交易投诉及其状态变化，应在支付宝开放平台应用中订阅“交易投诉通知”。配置时建议核对接口标识，通常为：

alipay.merchant.tradecomplain.notify

控制台中的中文名称可能是“交易投诉通知”“商家交易投诉通知”或类似名称，具体取决于开放平台当前页面以及应用已开通的能力。

为什么列表接口可能只查到“小程序投诉”

alipay.merchant.tradecomplain.batchquery 不是“小程序投诉专用接口”。能否查到支付交易投诉，主要取决于以下条件：

当前应用是否已开通交易投诉相关产品或能力。
应用是否绑定了发生投诉的支付宝商家账号。
调用接口所用的 app_id、商家身份与投诉所属主体是否一致。
查询时间范围、投诉状态等筛选条件是否覆盖目标投诉。
支付交易投诉是否已进入开放平台提供的投诉处理范围。

如果商家后台能看到支付交易投诉，但接口始终查不到，应先核对应用授权和商家主体关系，不要直接认定还需要另一套 API。

接入步骤

1. 查找接口文档

登录支付宝开放平台，在文档或 API 搜索中直接搜索：

alipay.merchant.tradecomplain.batchquery
alipay.merchant.tradecomplain.query
alipay.merchant.tradecomplain.notify

也可以从应用已开通能力中的“交易投诉处理”进入接口目录。开放平台的文档地址和控制台入口可能调整，因此通过 API 标识搜索通常比保存固定页面地址更可靠。

2. 开通投诉处理能力

在需要接收投诉的应用下开通交易投诉相关能力，并逐项确认：

应用所属商家与被投诉交易的收款商家一致；
应用具有投诉查询和处理权限；
第三方应用已获得商家的对应授权；
应用使用生产环境配置，而不是沙箱环境配置。

3. 订阅交易投诉通知

进入应用的消息订阅或消息服务配置页面，订阅交易投诉类消息，并填写可通过公网访问的 HTTPS 通知地址。

完成配置后，还要确认：

通知地址可以接收支付宝发送的 POST 请求；
使用支付宝公钥验签；
验签成功并完成受理后返回 success；
接口可以幂等处理消息；
如果业务处理耗时较长，应先持久化消息，再异步处理。

异步通知适合实时触发，但不能完全代替主动查询。生产环境通常还需要定时调用 alipay.merchant.tradecomplain.batchquery，补查可能遗漏的通知。

Java 验签示例

下面的示例演示支付宝常见表单通知的验签和响应方式。通知字段应以 alipay.merchant.tradecomplain.notify 的当前文档为准，不要自行假定投诉编号、状态等字段一定存在。

import com.alipay.api.internal.util.AlipaySignature;

import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;

public void handleComplaintNotify(
        HttpServletRequest request,
        HttpServletResponse response
) throws Exception {

    Map<String, String> params = new HashMap<>();

    for (Map.Entry<String, String[]> entry
            : request.getParameterMap().entrySet()) {
        String[] values = entry.getValue();
        params.put(
            entry.getKey(),
            values == null ? "" : String.join(",", values)
        );
    }

    boolean verified = AlipaySignature.rsaCheckV1(
        params,
        ALIPAY_PUBLIC_KEY,
        "UTF-8",
        "RSA2"
    );

    if (!verified) {
        response.setStatus(HttpServletResponse.SC_BAD_REQUEST);
        response.getWriter().print("failure");
        return;
    }

    // 从验签后的 params 中读取文档规定的投诉编号、交易号和状态等字段。
    // 使用通知唯一标识或“投诉编号 + 状态”实现幂等。
    saveAndProcessIdempotently(params);

    response.setContentType("text/plain;charset=UTF-8");
    response.getWriter().print("success");
}

如果当前通知文档使用 JSON 消息体或信封格式，应按照文档规定的签名原文拼接规则验签，不能直接套用表单参数示例。

主动查询示例

使用支付宝 Java SDK 查询投诉列表时，业务参数必须按照当前接口文档填写。下面只展示调用结构，不虚构具体的查询字段：

AlipayClient alipayClient = new DefaultAlipayClient(
    gatewayUrl,
    appId,
    merchantPrivateKey,
    "json",
    "UTF-8",
    alipayPublicKey,
    "RSA2"
);

AlipayMerchantTradecomplainBatchqueryRequest request =
    new AlipayMerchantTradecomplainBatchqueryRequest();

request.setBizContent("""
{
  // 按当前接口文档填写查询时间、分页信息和状态等参数
}
""");

AlipayMerchantTradecomplainBatchqueryResponse result =
    alipayClient.execute(request);

if (!result.isSuccess()) {
    throw new IllegalStateException(
        result.getCode() + ": " + result.getSubMsg()
    );
}

注意事项

notify_url 和消息订阅地址不是同一个概念。支付下单接口中的 notify_url 用于接收支付结果，不会自动接收交易投诉。
不要只根据页面上的中文消息名称判断，应优先核对消息对应的接口标识。
收到通知后必须先验签，再使用其中的投诉编号、交易号和状态。
返回内容通常要求为纯文本 success，不要返回 JSON、HTML 或额外空格。具体要求以通知文档为准。
通知可能重复发送，送达顺序也可能变化。处理逻辑必须支持幂等，并以投诉详情查询结果作为最终状态依据。
如果控制台搜索不到 alipay.merchant.tradecomplain.notify，通常表示当前应用类型、商家主体或产品权限尚未满足条件。此时需要在开放平台工单中提供 app_id、商家 PID 和示例投诉编号，以便核查权限。