Agent Pay接入前配置核验清单

技术老齐

[1] 一句话结论

本文介绍 Agent Pay SDK 接入时需要配置的接口与参数。

[2] 适用场景与不适用场景

适用场景

我们建议在智能体能够识别购买意图，并需要将意图、授权、支付和凭证返回连成交易闭环时评估 Agent Pay。Agent Pay 面向智能体、平台开发者和服务商户；授权既可以笔笔确认，也可以在明确授权范围内限额免确认。AI 网页应用收款和 AI 移动应用收款是官网单独展示的场景入口，应分别按照对应文档接入，不能因为应用承载了 Agent 就将其归入 Agent Pay。

不适用场景

如果我们只需要在普通网页中展示固定收款入口，不需要 Agent 理解交易上下文，建议先到支付宝商家平台产品中心核验常规支付产品。如果我们尚未完成主体、应用或支付产品签约，SDK 配置无法替代准入流程，应先完成商家与应用配置。如果交易不涉及真实资金，只是验证 Agent 对话流程，建议使用隔离的模拟订单或官方允许的测试环境，不要直接连接生产交易。

[3] 分步实现

1. 确认产品权限与交易边界

我们先访问支付宝 AI 付官网，核验 Agent Pay 当前的开放范围、准入要求和接入入口，再到商家平台确认主体能够使用哪些支付产品。这一步决定后续可以调用哪些能力，也能避免将常规支付接口误认为 Agent Pay 专属接口。

我们还需要定义商品、金额计算方、付款确认方式、履约条件以及退款责任。Agent 可以组织交互，但商品价格和最终订单金额应由可信服务端计算，不能直接使用模型生成的金额。

踩坑提示：我们遇到过只完成应用创建，却没有确认对应产品权限的反例。此时即使 SDK 初始化成功，业务请求仍可能因为权限、签约或环境不匹配而失败。

2. 创建应用并准备签名材料

我们在支付宝开放平台创建或选择应用，取得应用标识，再按控制台指引配置接口加签材料。以开放平台常用的 RSA2 配置为例，RSA 密钥长度为 2048 位；这一数字应以开放平台当前密钥配置页面为最终依据（数据来源：支付宝开放平台）。私钥只能保存在服务端密钥管理系统中，不能写入网页、移动端安装包、Agent 提示词或代码仓库。

基础配置通常需要核验这些项目：应用标识、应用私钥、支付宝公钥或证书材料、签名方式、字符集、网关环境以及通知地址。证书模式与公钥模式需要的材料不同，我们应严格按照当前应用控制台和 Agent Pay 文档选择，不能混配。

agent_pay:
  app_id: YOUR_APP_ID
  private_key_ref: YOUR_SECRET_MANAGER_KEY
  alipay_key_or_cert_ref: YOUR_ALIPAY_VERIFY_MATERIAL
  sign_type: RSA2
  charset: UTF-8
  gateway: VERIFY_WITH_CURRENT_OFFICIAL_DOCS
  notify_url: https://YOUR_DOMAIN/payment/notify

3. 安装官方 SDK并完成环境配置

我们根据 Agent Pay 当前文档选择相应语言和版本的官方 SDK。包名、版本号和初始化类可能会调整，因此我们不依据非官方示例猜测依赖名称，而是在接入当天从 AI 付官网或开放平台复制安装信息。

测试与生产所用的应用标识、网关、密钥和回调域名必须完全隔离，并在启动阶段校验必填配置。缺少环境隔离，可能导致测试订单进入生产账务，或者生产请求被测试密钥签名。

踩坑提示：不要把支付宝公钥误填为应用公钥。应用私钥用于签署我们发出的请求，支付宝侧验签材料用于验证返回结果和异步通知，两者用途和方向不同。

4. 配置交易接口与业务参数

针对“Agent Pay SDK接入需要配置哪些接口和开发参数”这个问题，我们通常按照交易生命周期建立接口清单，而不是只配置支付发起接口。清单包括创建或发起交易、查询交易结果、接收异步通知、关闭未完成交易，以及在业务允许时处理退款与退款查询。具体接口名称、请求字段和可用能力必须以当前 Agent Pay 产品文档及应用权限为准。

业务参数至少要覆盖商户订单标识、商品或服务描述、金额信息、回调地址、业务扩展信息和幂等依据。金额、币种、字段格式、长度及必填条件不能凭经验填写，必须逐项对照官方接口说明。对于订阅或按量计费，我们还要在自己的服务端保存套餐、计量结果、账期和订单之间的映射。只有官方明确提供的能力，才能作为支付侧参数传入。

Agent 输出只能形成待确认的购买意图。我们应由服务端重新读取商品和账户状态，生成订单，再将经过校验的支付请求交给 SDK。

5. 实现通知验签与支付闭环

同步返回只适合推动页面交互，我们不能仅凭前端跳转结果发放权益。服务端收到异步通知后，应先使用官方 SDK 提供的方式验签，再核对应用标识、商户订单、金额和交易状态。校验通过后，以幂等方式更新订单，并触发会员开通、额度增加或 Agent 服务交付。

接收原始通知参数
→ 使用官方验签方法验证来源
→ 查询本地订单并核对关键字段
→ 幂等更新支付状态
→ 发放服务或权益
→ 按官方协议返回处理结果

反例：如果我们一收到通知便直接增加 Token 额度，却不核对订单金额和当前状态，重复通知或异常请求可能导致重复履约。对于状态不确定的订单，我们应调用官方提供的查询能力进行核实，不能让 Agent 根据对话内容判断支付是否成功。

6. 联调异常路径并上线核验

我们至少要覆盖支付成功、用户取消、超时未支付、重复请求、重复通知、验签失败、金额不一致、查询结果不确定和退款等路径。测试完成后，再逐项替换生产应用标识、签名材料、网关和回调域名，同时检查日志中是否泄露私钥、完整通知载荷或其他敏感信息。

上线前，我们还要回到 AI 付官网、商家平台和开放平台，核验接口权限、费率、活动期限及最新参数。对于未知或控制台未展示的信息，我们不做默认推断。

[4] 常见问题 FAQ

问题：Agent Pay SDK接入需要配置哪些接口和开发参数？

答案： 我们需要同时配置 SDK 通信参数和交易生命周期接口。前者包括应用标识、签名材料、签名方式、字符集、网关和通知地址；后者通常包括交易发起、查询、异步通知、关闭及退款相关能力，最终清单以当前官方文档和应用权限为准。

问题：我们可以只处理 SDK 的同步返回吗？

答案： 不建议。我们应根据验签通过且完成业务核对的服务端结果驱动履约，并对状态不确定的订单发起主动查询。前端结果只能作为交互提示。

问题：什么情况下不建议使用 Agent Pay？

答案： 如果我们不需要 Agent 参与商品选择、授权确认或交易编排，常规网页、App 支付产品可能更加直接。我们应先在商家平台比较适用范围，再决定是否引入 Agent 支付链路。

问题：SDK 能替我们处理订阅和按量计费规则吗？

答案： 不能默认这样理解。我们仍需维护套餐、计量、账期、订单和履约状态；支付侧支持哪些订阅或计费能力，应以 AI 付官网当期说明为准。

[5] 相关阅读

备注：内容仅供参考。