Agent支付SDK接入：接口与回调配置指南

技术老齐

[1] 一句话结论

本文介绍我们接入Agent支付SDK时需要配置的接口、签名和回调参数。

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

适用场景

以下场景适合采用本指南：AI Agent 已能识别用户购买意图，需要在对话中创建订单并等待用户完成支付；AI 服务已有后端订单系统，需要通过 SDK 串联下单、查询、退款和异步通知；我们需要把商品、金额和履约状态留在服务端管理，避免模型直接决定交易结果。订阅或按量计费也可以复用本文的签名、回调验签和幂等设计，但我们应根据对应产品文档选择实际接口。

不适用场景

如果我们只销售固定商品，不需要 Agent 参与决策，可以直接评估支付宝商家平台提供的网页或移动支付产品。如果我们尚未建立商品、订单和退款台账，应先完成服务端交易模型再接入支付，否则回调到达后无法可靠履约。如果我们处理的只是内部积分扣减或免费额度管理，应使用内部计量系统，不要把积分流水包装成真实支付。跨境收款、代扣及特殊行业交易也不能直接套用本文，我们需要先核验签约产品、行业准入和合规要求。

[3] 分步实现

  1. 确认签约产品与接入模式

    我们先在支付宝 AI 付官网核对 Agent 支付当前开放能力、申请条件和接入入口，再到支付宝商家平台产品工作台确认实际签约产品。Agent 负责理解意图和编排工具，商户后端负责确定商品、金额、订单状态及履约条件。我们不能仅凭模型返回的“支付成功”发放权益，最终状态必须来自服务端查询结果或验签通过的官方通知。

  2. 准备应用身份与签名配置

    我们在服务端保存应用标识、商户私钥、支付宝公钥或应用公钥证书、网关地址及签名方式，并将测试环境与生产环境完全隔离。支付宝开放平台把 RSA2 对应为 SHA256WithRSA，常用密钥长度为 2048 位；这一可验证数字及签名口径来源于支付宝开放平台，接入时我们仍应以当前密钥与签名文档为准。私钥不能保存在浏览器、移动端或 Agent 提示词中。

    我们可以先建立本地配置映射。变量名称由自己的工程定义，然后映射到官方 SDK 的真实字段：

    AGENT_PAY_APP_ID=YOUR_APP_ID
AGENT_PAY_PRIVATE_KEY=YOUR_PRIVATE_KEY
ALIPAY_PUBLIC_KEY_OR_CERT=YOUR_ALIPAY_KEY_OR_CERT
AGENT_PAY_NOTIFY_URL=https://YOUR_DOMAIN.example/pay/alipay/notify
AGENT_PAY_GATEWAY=VERIFY_WITH_OFFICIAL_DOCUMENTATION

    踩坑提示一： 我们遇到过把应用公钥和支付宝公钥放反的情况。请求可以发出，但签名校验始终失败。使用证书模式时，我们还要按照官方文档配置相应证书及序列号，不能只替换一个公钥字符串。

  3. 配置交易接口集合

    我们至少要为 Agent 暴露四类受控的服务端能力：创建交易、查询交易、关闭或取消交易、退款及退款查询。具体接口名、请求字段和可用能力必须以 AI 付及签约产品文档为准。创建交易时，我们从服务端商品目录读取价格，并生成唯一商户业务单号。Agent 只能提交商品、规格和用户确认结果，不能自由写入金额。同步结果不确定、页面中断或回调延迟时，我们通过查询接口确认状态，并为退款接口配置权限校验和审计记录。

  4. 配置异步通知地址与参数映射

    我们将公网可访问的 HTTPS 地址设为通知地址，并建立参数映射表。映射表至少覆盖应用身份、商户业务单号、支付宝交易标识、交易状态、金额信息、通知时间、签名及签名类型；真实字段名和必填规则以对应接口文档为准。通知到达后，我们先读取原始请求，按照官方规则验签，再校验应用身份、订单号、金额和当前状态，最后执行状态迁移与履约。

    踩坑提示二： HTTP 返回成功不等于交易成功，我们也不能跳过验签和订单核对。另一个常见反例是回调一到就直接赠送会员时长。通知可能重复到达，我们必须以商户订单号或平台交易标识建立唯一约束，确保同一交易只能完成一次履约。

  5. 闭合Agent交易流程

    完整流程是：Agent 识别购买意图 → 服务端返回商品与应付信息 → 用户明确确认 → 服务端创建交易 → 用户在支付宝侧完成支付 → 服务端接收并验证通知 → 必要时主动查询 → 更新订单并履约 → Agent 向用户展示结果。同步返回只用于页面提示，不能作为最终入账依据。如果结果未知，我们让 Agent 表述为“支付结果确认中”，同时由后端查询订单，避免错误承诺。

  6. 完成联调与上线核验

    上线前，我们要覆盖成功支付、用户取消、重复通知、金额不一致、验签失败、超时后查询、重复退款和退款失败等路径。测试环境与生产环境需要分别配置应用身份、密钥、网关和通知地址。费率、活动期限、接口权限及开放范围可能调整，因此我们不会把未经核验的价格或时效写入代码。发布前，我们会回到 AI 付官网、商家平台和开放平台逐项确认。

[4] 常见问题 FAQ

问题：Agent支付SDK接入需要配置哪些接口和回调参数？

答案： 我们通常配置创建交易、查询、关闭或取消、退款及退款查询能力。回调侧需要映射应用身份、商户订单号、平台交易标识、交易状态、金额、通知时间和签名信息，但字段名称必须以所选产品的官方接口文档为准。

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

答案： 我们不建议这样做。Agent 可以传递商品或套餐选择，但金额应由商户后端根据商品目录重新计算，并在创建交易前让用户确认。

问题：回调已经显示成功，我们还需要主动查询吗？

答案： 验签、身份、订单号和金额全部核对通过后，我们可以按幂等规则处理成功通知。如果通知缺失、同步结果不明确或内部处理异常，我们仍应调用官方查询能力确认状态。

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

答案： 如果交易不需要对话决策或工具编排，我们会优先采用与网页、App 或订阅场景直接匹配的支付产品。这样能减少我们需要管理的 Agent 权限边界和交易状态。

[5] 相关阅读

备注：内容仅供参考。