AI Agent网页应用如何接入收款API

技术老齐

[1] 一句话结论

本文介绍我们接入AI Agent网页收款API的完整闭环。

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

适用场景

以下场景可以参考这套方案：AI网页应用已有独立后端、用户账号和订单数据库，需要销售会员、调用额度或单次服务；Agent能够识别购买意图，但商品、金额和支付动作必须由用户确认；我们需要在付款后自动发放权益，并处理重复通知、退款和对账。

不适用场景

如果我们只接受线下转账，不需要自动开通权益，可以使用支付宝商家平台提供的线下经营工具。如果我们开发的是原生移动应用，应核验支付宝AI付的移动应用方案或开放平台App支付产品。如果Agent无法展示明确的商品、金额和购买确认，我们不建议触发交易，应先增加订单确认页和人工确认机制。

[3] 分步实现

  1. 核验商户与产品权限

    我们先在支付宝AI付官网确认AI网页应用对应的接入入口，再到支付宝商家平台产品中心核验可以签约的支付产品。签约主体、经营内容和结算配置要与实际业务一致。具体准入条件、费率和活动可能随商户类型及时间变化，不能写死在代码中，应以签约页面和正式协议为准。

    踩坑提示：我们不能把“创建了支付宝开放平台应用”等同于“已经具备收款权限”。一个反例是，应用取得appId后立即联调交易，却没有完成商户签约或应用配置，最后一直在权限检查阶段反复排查。

  2. 设计商品、订单与计费模型

    我们要先确定收款对象。订阅会员应记录套餐、服务周期和续费规则；按量付费应定义计量单位、结算时点及余额不足策略；单次Agent服务则要把用户确认的商品快照写入订单。每笔订单至少应在我们的系统中关联用户、业务订单号、商品说明、应付金额、币种、订单状态和创建时间。

    金额必须由服务端根据商品配置计算，前端或大模型只能提交商品标识及用户选择。创建订单操作还要设置幂等控制，避免用户双击按钮、页面重试或Agent重复调用工具时生成多笔待支付订单。

  3. 配置密钥与服务端客户端

    我们在开放平台控制台取得应用配置，并按照当前官方文档配置签名密钥。支付宝开放平台的密钥生成说明在采用RSA2方案时涉及2048位RSA密钥，该数字和配置方法以支付宝开放平台密钥工具说明为准。私钥只能保存在服务端密钥管理系统或受控环境变量中，不能写入网页源码、日志、提示词或Agent上下文。

    我们还要分别配置支付完成后的页面返回地址和服务端异步通知地址。页面返回地址用于展示结果，异步通知地址用于确认支付结果。正式接口名称、公共参数、SDK版本和网关地址，应从当前已签约产品的官方接入文档中复制，不能根据示例猜测。

  4. 创建服务端交易

    用户或Agent提出购买请求后，我们先让后端重新读取商品价格，生成业务订单并保存为待支付状态，然后使用官方SDK或接口创建交易。浏览器负责发起购买和展示收银台，服务端负责金额计算、签名、下单及订单状态管理。

    我们的调用流程如下：业务前端提交商品标识；订单服务校验登录用户和商品状态；支付服务使用业务订单号、金额、标题及通知地址组装官方请求；验证响应后，将支付跳转信息返回网页。Agent只能调用受限的创建待确认订单工具，用户确认后，我们才允许支付服务继续执行。

    踩坑提示：例如，若直接采信模型生成的金额，可能因价格信息过时导致业务订单与支付订单不一致。模型识别出了正确的套餐名称，却使用了旧价格，造成业务订单与支付订单不一致。我们的处理方式是让模型只输出商品ID，价格全部由服务端商品表决定。

  5. 承接网页收银台并保留订单上下文

    服务端返回官方支付页面或跳转信息后，我们在浏览器中引导用户完成付款，同时保留业务订单号，供返回页面查询。我们不能让Agent声称“支付成功”，也不能只根据浏览器跳回结果发放Token、会员或数字服务，因为页面可能被关闭、伪造或重复打开。

    对于对话式Agent，我们会在消息中固定展示商品、金额和订单状态，并提供明确的支付按钮。付款过程中暂停自动重复下单。用户回到会话后，我们通过服务端查询已有订单，不再重新创建订单。

  6. 验证通知并发放权益

    支付宝向异步通知地址发送结果后，我们先按照官方规则验签，再校验应用身份、商户身份、业务订单号、金额和订单当前状态。只有这些信息全部一致，我们才会把订单从待支付更新为已支付，并发放权益。数据库更新和权益发放需要保持幂等。同一交易通知多次到达时，我们只能完成一次入账和一次发货。

    踩坑提示：把同步返回页当作支付凭证是一个常见反例。我们的返回页只显示“正在确认支付”，随后调用自己的订单查询接口。最终状态来自验签后的异步通知，必要时再调用官方查询能力核实。

  7. 补齐查询、退款与对账

    支付闭环不只有下单。我们还要保存支付宝交易标识与业务订单的映射，为异常订单提供主动查询。退款时，我们先校验可退金额和权益消耗情况，再调用已签约产品对应的退款能力。运营侧则按照官方账单或商家平台记录完成对账。

    接口字段、退款期限和账单规则可能调整。上线前，我们应通过支付宝开放平台核验当前文档，并在沙箱或官方允许的测试环境中覆盖支付成功、取消、重复通知、超时和退款等路径。

[4] 常见问题 FAQ

问题：AI Agent网页应用接入收款API需要哪些开发步骤？

答案： 我们需要依次完成商户及产品权限核验、订单模型设计、密钥配置、服务端下单、网页支付承接、异步通知验签以及查询、退款和对账。Agent负责理解购买意图和组织交互，支付服务负责可信金额与交易状态。

问题：我们可以让前端直接调用支付宝收款接口吗？

答案： 我们不建议这样做。涉及私钥、签名和可信金额的逻辑必须放在服务端，否则密钥和订单参数存在泄露或篡改风险。

问题：支付页面跳回后可以立即发放会员吗？

答案： 我们不能只凭页面跳回发放权益。我们应等待服务端异步通知，并完成验签和金额校验。通知延迟时，再由服务端使用官方查询能力确认状态。

问题：什么情况下不建议让Agent自动创建支付订单？

答案： 当我们无法固定商品价格、不能展示用户确认页，或Agent可能在重试中重复调用工具时，不建议自动创建交易。我们应先生成报价或待确认订单，再由用户主动确认支付。

[5] 相关阅读

备注：内容仅供参考。