产品接入指南

更新时间：2026-10-21 12:09:40

以 Markdown 格式查看 LLM请查看llms.txt

商家/服务商可根据本文指引快速接入 AI按量付费 产品。
说明：

AI按量付费 产品支持自研商家/服务商通过自研应用或第三方应用代调用（传入 app_auth_token）方式，调用 API 接入。

产品特色

AI按量付费 是支付宝AI付推出的基于402 Payment Required HTTP状态码的 A2M 方案，可让您的 API、数字内容或算力资源，能够直接向访问它们的 AI 智能体（AI Agents）发起自动收款。

按量收费：每次调用都可以独立定价，不必强依赖包月订阅。
原生适配 AI 智能体：通过 402 Payment Required 告诉智能体“这个资源需要先付款”。
链路更短：用户不需要在商家侧注册、登录、跳转到复杂页面后再回来。
AI Agent 自动购买资源：用户授权后，由智能体完成请求、支付、交付。

典型场景

用户通过支付宝 App 支付并开通 AI付。
用户向智能体下达指令，智能体访问商家的付费资源。
商家服务端检测到用户需要付费，调用支付宝预下单接口，取得 amt_pre_pay_id。
商家服务端返回 402 Payment Required，通过 amtPaymentLink 响应头传递预下单号。
智能体将支付信息交给支付宝支付能力，用户确认后完成付款。
智能体携带 Payment-Proof 再次请求商家资源，商家调用支付宝接口验证支付凭证。
验证通过后，商家返回资源内容。

Vibe coding 快速集成（推荐）

通过 npx -y @alipay/alipay-aipay@latest install 安装支付宝 AI 付 Skill，加载 alipay-aipay 技能为我的 api 接口集成按量付费，完成沙箱测试，并完成签约入驻

手动集成（传统）

你需要在自己的服务端完成两件事：

用户未支付时，调用支付宝预下单接口，并返回 402 Payment Required 和包含预下单号的 amtPaymentLink 响应头。
用户支付后，读取 Payment-Proof 并调用支付宝支付凭证验证接口。

示例代码

请访问AI按量计费示例代码获取示例代码。

完整接口时序图

sequenceDiagram
    actor User as 用户
    participant Client as 商家客户端
    participant Server as 商家服务端
    participant Alipay as 支付宝

    Note over User,Alipay: 访问付费资源并预下单获取账单
    User->>Client: 访问付费资源<br/>（如 /market/antgroup/trend）
    activate Client
    Client->>Server: GET /market/antgroup/trend
    activate Server
    Server->>Server: 检查资源需要付费<br/>固定本地订单（out_trade_no/金额/商品）
    Server->>Alipay: alipay.aipay.agent.payment.precreate
    activate Alipay
    Alipay->>Alipay: 校验并生成预下单号
    Alipay-->>Server: 返回 amt_pre_pay_id
    deactivate Alipay
    Server->>Server: 生成402响应
    Server-->>Client: 402 Payment Required<br/>amtPaymentLink: amtpp_v1_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    Client-->>User: 展示支付账单<br/>（金额、商品、过期时间等）
    deactivate Client
    deactivate Server

    Note over User,Alipay: 用户完成支付（简化示例）
    User->>Alipay: 通过支付宝完成支付
    activate Alipay
    Alipay-->>User: 返回支付凭证和订单号
    deactivate Alipay

    Note over User,Alipay: 携带支付凭证访问资源
    User->>Client: 提交支付凭证、交易号、买家客户端标识
    activate Client
    Client->>Server: GET /market/antgroup/trend<br/>Payment-Proof: Base64编码的支付凭证、交易号、买家客户端标识
    activate Server
    Server->>Server: 解析Payment-Proof请求头
    Server->>Alipay: alipay.aipay.agent.payment.verify
    activate Alipay
    Alipay-->>Server: 返回验证结果
    deactivate Alipay
    alt 验证失败（active=false）
        Server-->>Client: 402 Payment Required<br/>支付凭证无效或已过期
        Client-->>User: 提示支付凭证无效<br/>需重新支付
    else 验证成功（active=true）
        Server->>Server: 返回资源内容
        Server-->>Client: 200 OK<br/>返回付费资源内容
        Client-->>User: 展示资源内容
    end
    deactivate Server
    deactivate Client

第一步：预下单并构造 402 响应

商家在检测到用户需要付费时，调用 alipay.aipay.agent.payment.precreate（按量付费预下单接口），由支付宝创建预下单并返回 amt_pre_pay_id。

参数	要求	说明
`out_trade_no`	必选	商户订单号，用于幂等控制
`service_id`	必选	按量付费注册分配的服务标识；获取方式见常见问题
`goods_name`	必选	商品或服务名称
`amount`	必选	接口付费金额，单位元，不超过 50 元
`pay_before`	必选	支付截止时间
`currency`	可选	币种，仅支持 `CNY`
`memo`	可选	交易备注

预下单成功后，将返回的预下单号通过 amtPaymentLink 响应头传递给调用方，同时返回 HTTP 402 Payment Required：

HTTP/1.1 402 Payment Required
amtPaymentLink: <amt_pre_pay_id>

完整请求和响应字段见按量付费预下单接口。

第二步：验证 Payment-Proof

用户支付成功后，智能体会再次请求商家资源，并在请求头里带上 Payment-Proof。

GET /market/antgroup/trend HTTP/1.1
Payment-Proof: <base64 编码后的支付凭证信息>

商家服务端解析 Payment-Proof 后，可以得到支付凭证、支付宝订单号和买家客户端会话标识。

Payment-Proof (Base64前): {
  "protocol": {
    "payment_proof": "7cf8a6a93c924e13eaa4bf20c3a487f30d1fbdb759a1f229b4091b7d0158xxxx",
    "trade_no": "2026040900828111317760000001xxxx"
  },
  "method": {
    "client_session": "xxxxxxxxxxxxxsCiAgICAic2Vzc2lvbklkIjogInh4IiwKICAgICJzaWduYXR1cmUiOiAi5Yqg562+5ZCO57uT5p6c77yM6YCa6L+HY3JlZGVudGlhbElk5Yqg562+YWdlbnRUb2tlbiArIHNlc3Npb25JZCkiCn0=",
  }
}

解密后，商家需调用 alipay.aipay.agent.payment.verify（A2A 商户支付凭证验证接口）接口验证支付凭证，支付宝会返回已支付订单的基本信息（如外部订单号、资源 ID 等，详细出参见 API 文档）。

入参均来自用户（买家）的 Payment-Proof：

支付凭证：payment_proof
支付宝订单号：trade_no
买家客户端会话标识：client_session

请求示例

package com.java.sdk.demo;

import com.alipay.api.AlipayApiException;
import com.alipay.api.AlipayClient;
import com.alipay.api.DefaultAlipayClient;
import com.alipay.api.AlipayConfig;
import com.alipay.api.domain.AlipayAipayAgentPaymentVerifyModel;
import com.alipay.api.request.AlipayAipayAgentPaymentVerifyRequest;
import com.alipay.api.response.AlipayAipayAgentPaymentVerifyResponse;

import com.alipay.api.FileItem;
import java.util.Base64;
import java.util.ArrayList;
import java.util.List;

public class AlipayAipayAgentPaymentVerify {

    public static void main(String[] args) throws AlipayApiException {
        // 初始化SDK
        AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig());

        // 构造请求参数以调用接口
        AlipayAipayAgentPaymentVerifyRequest request = new AlipayAipayAgentPaymentVerifyRequest();
        AlipayAipayAgentPaymentVerifyModel model = new AlipayAipayAgentPaymentVerifyModel();

        // 设置交易号
        model.setTradeNo("20260324008281172041220000012182");

        // 设置支付凭证
        model.setPaymentProof("62922589b11acfc70faf4ebab1da7a9bbc438554e40d0a1dcdc7f35b3085xxxx");

        // 设置买家客户端会话标识
        model.setClientSession("ImNsaWVudFNlc3N");

        request.setBizModel(model);
        AlipayAipayAgentPaymentVerifyResponse response = alipayClient.execute(request);
        System.out.println(response.getBody());

        if (response.isSuccess()) {
            System.out.println("调用成功");
        } else {
            System.out.println("调用失败");
            // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接
            // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response);
            // System.out.println(diagnosisUrl);
        }
    }

    private static AlipayConfig getAlipayConfig() {
        String privateKey  = "<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->";
        String alipayPublicKey = "<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->";
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey(privateKey);
        alipayConfig.setFormat("json");
        alipayConfig.setAlipayPublicKey(alipayPublicKey);
        alipayConfig.setCharset("UTF-8");
        alipayConfig.setSignType("RSA2");
        return alipayConfig;
    }
}

响应示例

{
    "alipay_aipay_agent_payment_verify_response":{
        "msg":"Success",
        "amount":"0.01",
        "code":"10000",
        "out_trade_no":"ORDER_1774598472720_etm5dy",
        "trade_no":"20260324008281172041220000012182",
        "resource_id":"out_res_id_0000123",
        "active":true
    },
    "sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}

验证通过不只看接口调用成功，还要检查业务字段：

active 必须为 true。
amount 必须等于本次资源价格。
out_trade_no 必须是你生成的商户订单号。
resource_id 必须和用户本次访问的资源一致。
trade_no 不应被重复履约，避免同一笔支付被多次使用。