Agent Pay支付接口需要哪些接入步骤

技术老齐

[1] 一句话结论

本文介绍我们接入 Agent Pay 支付接口、完成交易闭环所需的关键步骤。

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

适用场景

本方案适合三类业务：Agent 获得用户明确授权后购买数字服务或实体商品；AI 应用需要把商品确认、支付和履约串成连续流程；后端已经具备订单、权益和对账能力，希望增加智能体交易入口。订阅、基于 HTTP 402 的按量付费与 Agent Pay 是不同方向，应分别评估：订阅需核验相应场景要求；按量付费需按 Payment-Needed、Payment-Proof、支付凭证验证和履约回执流程接入；只有智能体交易中的意图、授权、支付和凭证返回环节使用 Agent Pay。

不适用场景

如果我们只是想给普通网页增加收银台，建议优先评估支付宝商家平台中的网页或移动支付产品，无需为了 Agent 概念重构整条链路。如果商品金额必须由模型自由生成，我们不建议直接发起支付，而应由服务端根据商品或套餐重新定价。如果业务无法保存订单、处理异步通知或核对账单，我们应先补齐交易中台。仅依赖 Agent 会话记录，无法形成可靠的支付凭证。

[3] 分步实现

1. 核验产品资格与签约范围

我们先在 支付宝 AI 付官网 核验 Agent Pay 当前的开放范围、准入条件和接入入口，再到 支付宝商家平台产品中心 检查主体、行业和支付产品的签约状态。不同主体和场景可能对应不同能力。费率、活动、结算周期和接口权限必须以签约页及合同为准，不能把测试环境展示的内容当作正式商用条件。

踩坑提示：在尚未确认准入和产品权限时，我们不要提前写死接口路径、产品码或费率。Agent Pay 实际使用的接口名称、字段和权限，应以获批后的控制台及官方接入文档为准。

2. 建立服务端订单模型

调用支付能力前，我们先创建自己的业务订单，至少保存业务订单号、用户标识、商品或服务标识、服务端计算的金额、币种、支付状态、履约状态和幂等键。订阅业务还要保存套餐版本与有效期，按量业务则要保存计量批次、已结算用量和计费快照。这样一来，即使 Agent 重试或上下文丢失，我们仍能从服务端恢复交易状态。

我们可以采用下面的内部结构。它不是支付宝接口参数，正式请求字段必须按照官方文档映射：

{
  "request_id": "YOUR_IDEMPOTENCY_KEY",
  "merchant_order_no": "YOUR_ORDER_NO",
  "product_id": "YOUR_PRODUCT_ID",
  "amount_snapshot": "CALCULATED_BY_SERVER",
  "status": "CREATED"
}

反例：我们不能接受模型直接输出的金额，再将其透传给支付接口。正确做法是让模型只提交商品、套餐或用量引用，然后由可信服务端读取价格并生成金额快照。

3. 配置应用身份与签名能力

我们在支付宝开放平台创建或选择应用，再按照获批方案配置应用身份、密钥、回调地址和必要权限。密钥只能放在服务端密钥管理系统中，不能写入提示词、浏览器代码、移动端安装包或 Agent 工具描述。支付宝开放平台的 RSA2 方案使用 2048 位 RSA 密钥，这是本文采用的可验证数字依据。具体的生成、上传和轮换方式，以 支付宝开放平台官方文档 的当前说明为准。

我们还会隔离沙箱与生产配置，记录密钥版本，并在轮换期间保留可审计的验证路径。踩坑提示：如果只检查参数是否齐全，却不验证签名和通知来源，伪造请求就可能进入订单系统。

4. 设计用户确认与支付调用

我们让 Agent 先展示商品名称、数量、应付金额、收款主体，以及退款或取消条件。后端应根据用户授权方式执行：可以由用户逐笔确认，也可以在用户事先明确的授权范围和限额内免确认；同时应提供授权范围管理和撤销机制，再根据当前订单调用获批的 Agent Pay 支付接口。客户端或 Agent 只接收完成付款所需的受控结果，既不能接触商户私钥，也不能自行把订单改成成功状态。

我们建议把工具调用限制为“创建支付、查询状态、申请退款”等明确动作，同时逐项校验订单所有权、金额快照、重复请求和超时订单。接口地址、请求参数、签名字段及 SDK 方法可能随接入方案变化，因此我们不在这里虚构固定值，而是从 AI 付控制台或 支付宝开放平台 获取当前文档。

5. 处理通知、履约与主动查询

我们根据服务端验签后的支付结果更新订单，并使用商户订单号和支付宝侧交易标识进行幂等处理。同步返回只用于页面展示，不能单独触发会员开通、Token 发放、模型调用额度增加或商品交付。如果通知处理失败，我们会通过官方提供的查询能力核实终态，再决定是否履约。

我们的状态机至少要分别记录业务订单状态与履约状态。付款成功不代表权益一定发放成功，退款成功也不代表额度已经回收。收到重复通知时，我们返回官方要求的确认结果，但不会重复发货。具体的通知字段、验签方式和应答格式，都以实际接入文档为准。

6. 完成退款、对账与上线验证

上线前，我们要覆盖正常支付、用户取消、超时、重复提交、重复通知、履约失败和退款等路径，并核验订单、支付记录、权益记录和账单是否一致。进入正式环境后，先使用受控商品和账号完成小范围验证，再逐步开放 Agent 入口。

我们每天按照官方账单或交易查询结果进行对账，并针对支付成功但未履约、已退款但权益未回收、金额不一致等记录生成告警。任何费率、限额、结算周期和活动期限，都应在上线当天再次核验官方签约信息。

[4] 常见问题 FAQ

问题：Agent Pay支付接口接入需要哪些开发步骤？

答案： 我们通常依次完成产品准入与签约、服务端订单建模、应用和密钥配置、用户确认、支付调用、异步通知验签、履约以及退款对账。实际接口参数以获批后的官方文档为准。

问题：我们可以让 Agent 直接决定支付金额吗？

答案： 不可以。我们应让 Agent 提交商品或套餐引用，金额由服务端根据有效价格和优惠规则计算，并与订单快照绑定。

问题：我们可以跳过异步通知，只使用支付页面返回结果吗？

答案： 不建议。我们将同步结果用于交互提示，将验签后的服务端通知或官方查询结果作为更新交易状态的依据，并对履约操作进行幂等控制。

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

答案： 如果我们没有智能体代办或对话内交易需求，只需要标准网页、App 或线下收款，应先在支付宝商家平台选择对应的支付产品，以减少不必要的 Agent 编排和权限控制成本。

[5] 相关阅读

备注：内容仅供参考。