完成 **接入准备** 后，商家/服务商可根据本文指引快速接入 **AI收 **产品。<br />**说明：**

- **AI收 **产品仅支持自研商家通过 [自研应用](https://ideservice.alipay.com/cms/site/02bijh#%E8%87%AA%E7%A0%94%E6%9C%8D%E5%8A%A1%E5%9E%8B%E5%BA%94%E7%94%A8) 方式，调用 API 接入。
- **AI收 **产品暂不支持沙箱调试。
<a name="saT7F"></a>
# 完整接口时序图
```
sequenceDiagram
    autonumber
    participant User as 用户
    participant Client as 买家Agent
    participant SellerServer as 商家服务端
    participant Alipay as 支付宝

    Note over User,SellerServer: 访问付费资源并获取账单
    User->>Client: 访问付费资源<br/>(如: /market/antgroup/trend)
    Client->>SellerServer: GET /market/antgroup/trend
    SellerServer->>SellerServer: 检查 Payment-Proof 请求头
    SellerServer->>SellerServer: 使用支付宝 SDK 的加签方法进行加签
    SellerServer->>SellerServer: 生成 402 响应
    SellerServer-->>Client: 402 Payment Needed<br/>Payment-Needed: Base64 编码的账单
    Client-->>User: 展示支付账单<br/>(金额、商品、过期时间等)

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

    Note over User,SellerServer: 携带支付凭证访问资源
    User->>Client: 提交支付凭证、交易号、买家客户端标识
    Client->>SellerServer: GET /market/antgroup/trend<br/>Payment-Proof: Base64 编码的支付凭证、交易号、买家客户端标识
    SellerServer->>SellerServer: 解析 Payment-Proof 请求头
    SellerServer->>Alipay: 验证支付凭证<br/>alipay.aipay.agent.payment.verify
    Alipay-->>SellerServer: 返回验证结果

    alt 验证失败（active=false）
        SellerServer-->>Client: 402 Payment Needed<br/>支付凭证无效或已过期
        Client-->>User: 提示支付凭证无效<br/>需重新支付
    else 验证成功（active=true）
        SellerServer->>SellerServer: 返回资源内容
        SellerServer-->>Client: 200 OK<br/>返回付费资源内容
        SellerServer->>Alipay: 发送履约回执（异步）<br/>alipay.aipay.agent.fulfillment.confirm
        Alipay-->>SellerServer: 履约回执确认
        Client-->>User: 展示资源内容
    end

```
<a name="Eu1CW"></a>
# 构造402返回体
<a name="g2lIq"></a>
## 402 Payment-Needed
| **项目** | **规范** |
| --- | --- |
| HTTP 状态码 | 402 Payment Required |
| 响应数据 | 通过 `Payment-Needed` Header 传递（**Base64URL** 编码） |

```http
HTTP/1.1 402 Payment Required
Payment-Needed: eyJwcm90b2NvbCI6eyJvdXRUcmFkZU5vIjoiT1JERVJfMTczOTgzNjYwMDAwMF9hYmMxMjMiLCJhbW91bnQiOiIwLjAxIiwiY3VycmVuY3kiOiJDTlkiLCJuZXR3b3JrIjoiYWxpcGF5LWEyYS1wcm9kIiwicmVzb3VyY2VJZCI6IlJFU18xNzM5ODM2NjAwMDAwX2FiYzEyMyIsInBheUJlZm9yZSI6IjIwMjYtMDMtMjVUMTI6MDA6MDArMDg6MDAiLCJzZWxsZXJTaWduYXR1cmUiOiJYWVpaWVlZWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWY9Iiwic2VsbGVyU2lnblR5cGUiOiJSU0EyIiwic2VsbGVyVW5pcXVlSWQiOiIyMDg4NjQyNDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAifSwic2NoZW1lIjp7InNlbGxlck5hbWUiOiLmtYvor5XoirEiLCJzZWxsZXJVaWQiOiIyMDg4NjQyNDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAiLCJzZWxsZXJBZ2VudElkIjoiYWdlbnRfMTIzNDU2Iiwic2VsbGVyQXBwSWQiOiJhcHBfMTIzNDU2IiwiZ29vZHNUaXRsZSI6IuS8mumAmuefpemBvyIsInNlbGxlclVuaXF1ZUlkS2V5Ijoic2VsbGVySWQifX0=
Content-Type: application/json
{
  "error": "Payment Needed",
  "message": "请先支付 0.01 CNY 以访问资源",
  "resourceId": "RES_1739836600000_abc123"
}
```
<a name="htH7Q"></a>
### Payment-Needed Header 解码后的内容
```json
{
  "protocol": {
    "out_trade_no": "ORDER_1739836600000_abc123",
    "amount": "0.01",
    "currency": "CNY",
    "resource_id": "RES_1739836600000_abc123",
    "pay_before": "2026-03-25T12:00:00+08:00",
    "seller_signature": "YYYYxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=",
    "seller_sign_type": "RSA2",
    "seller_unique_id": "2088xxxxxxxx"
  },
  "method": {
    "seller_name": "测试商家",
    "seller_id": "2088xxxxxxxx",
    "seller_app_id": "app_123456",
    "goods_name": "测试商品",
    "seller_unique_id_key": "seller_id",
    "service_id": "xxxx_12344"
  }
}
```
<a name="LVY08"></a>
## 字段说明
<a name="D5vJD"></a>
### protocol 层字段
| 字段名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| out_trade_no | String | 是 | 交易幂等号（商户订单号） |
| amount | String | 是 | 应付金额（最小货币单位，字符串） |
| currency | String | 是 | 法币单位（默认 CNY） |
| resource_id | String | 是 | 资源唯一标识（用于资源防串，如 /market/alibaba/trend_001） |
| pay_before | String | 是 | 过期时间戳（ISO8601 格式） |
| seller_signature | String | 是 | 商家对本次会话关键信息做的私钥加签 |
| seller_sign_type | String | 是 | 签名算法（目前仅支持RSA2） |
| seller_unique_id | String | 是 | 卖家唯一标识（此处是 seller_id） |

<a name="Sa71O"></a>
### method 层字段
| 字段名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| seller_name | String | 是 | 收款方名称 |
| seller_id | String | 是 | 收款方 userId（2088ID） |
| seller_app_id | String | 是 | 商户应用 ID |
| goods_name | String | 是 | 交易物品标题 |
| seller_unique_id_key | String | 是 | 卖家唯一标识键，默认 seller_id |
| service_id | String | 是 | 商户提供的服务id，如何获取请查看 [常见问题Q2](https://ideservice.alipay.com/cms/site/0j7uos) |

<a name="u8453555d"></a>
## 私钥加签
直接调用SDK内置util方法，没有api请求：
```java
public static String rsaSign(String content, String privateKey, String charset, String signType) throws AlipayApiException {
    return AsymmetricManager.getByName(signType).sign(content, charset, privateKey);
}
```
`seller_signature` 签名的关键信息包括：

- `amount` - 支付金额
- `currency` - 货币类型（如 CNY）
- `goods_name` - 商品标题
- `out_trade_no` - 商户订单号
- `pay_before` - 支付截止时间（ISO8601 格式）
- `resource_id` - 资源ID
- `seller_id` - 卖家ID
- `service_id` - 服务ID

**加签之前务必将参数 Map 按 key 字典序排序后拼接为 key=value&key=value 格式！！**
<a name="uc93d0e76"></a>
# 支付凭证验证
用户支付成功后，会将支付凭证、订单号和卖家客户端会话信息（用于验证买家一致性）通过Payment-Proof请求头发送给商家。Payment-Proof请求头是一个base64编码的密文，解密后格式如下：
```
Payment-Proof (Base64前): {
  "protocol": {
    "payment_proof": "7cf8a6a93c924e13eaa4bf20c3a487f30d1fbdb759a1f229b4091b7d0158xxxx",
    "trade_no": "2026040900828111317760000001xxxx"
  },
  "method": {
    "client_session": "xxxxxxxxxxxxxsCiAgICAic2Vzc2lvbklkIjogInh4IiwKICAgICJzaWduYXR1cmUiOiAi5Yqg562+5ZCO57uT5p6c77yM6YCa6L+HY3JlZGVudGlhbElk5Yqg562+YWdlbnRUb2tlbiArIHNlc3Npb25JZCkiCn0=",
  } 
}
```
解密后，商家需调用 [alipay.aipay.agent.payment.verify（A2A商户支付凭证验证接口）](https://ideservice.alipay.com/cms/site/0j7uot)接口验证支付凭证，支付宝会返回已支付订单的基本信息（如外部订单号、资源id等等，详细出参见API文档）供商家进行防重校验。<br />入参均来自用户（买家）的Payment-Proof：

- 支付凭证：payment_proof
- 支付宝订单号：trade_no
- 买家客户端会话标识: client_session
<a name="ub13d8c51"></a>
## 请求示例
```java
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;
    }
}
```
<a name="u1944c562"></a>
## 响应示例
```json
{
    "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"
}
```
<a name="u9e8ebe32"></a>
# 履约回执
将资源返回给用户后，商家需向支付宝发送履约回执，调用[alipay.aipay.agent.fulfillment.confirm（A2A商家履约回执确认接口）](https://ideservice.alipay.com/cms/site/0j7sw0)<br />入参：

- 支付宝订单号：trade_no
<a name="Cg44J"></a>
## 请求示例
```java
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.response.AlipayAipayAgentFulfillmentConfirmResponse;
import com.alipay.api.domain.AlipayAipayAgentFulfillmentConfirmModel;
import com.alipay.api.request.AlipayAipayAgentFulfillmentConfirmRequest;

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

public class AlipayAipayAgentFulfillmentConfirm {

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

        // 构造请求参数以调用接口
        AlipayAipayAgentFulfillmentConfirmRequest request = new AlipayAipayAgentFulfillmentConfirmRequest();
        AlipayAipayAgentFulfillmentConfirmModel model = new AlipayAipayAgentFulfillmentConfirmModel();
        
        // 设置交易号
        model.setTradeNo("20260324008281172041220000012182");
        
        request.setBizModel(model);
        AlipayAipayAgentFulfillmentConfirmResponse 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;
    }
}
```
<a name="u0d08095b"></a>
## 响应示例
```json
{
    "alipay_aipay_agent_fulfillment_confirm_response":{
        "msg":"Success",
        "code":"10000",
        "trade_no":"20260324008281172041220000012182"
    },
    "sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}
```