Agent支付SDK接入：先验签再履约

技术老齐

[1] 一句话结论

本文介绍Agent支付SDK接入与自动收款闭环。

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

适用场景

本指南适用于三类场景：Agent在用户确认商品、服务内容和金额后发起交易，服务端统一创建订单；AI应用销售会员、推理额度或数字化服务，需要将支付状态与账号权益绑定；Agent作为咨询、选购或下单入口，订单、支付通知和履约仍由可信后端控制。无论使用网页端还是移动端，我们都应先到支付宝AI付官网核对当前开放能力和接入条件。

不适用场景

如果我们只需要普通网页收银台，不需要Agent参与交易决策，可以从支付宝商家平台支付产品中选择常规支付方案。如果我们还无法建立服务端订单系统，应先补齐订单、账务和幂等能力。如果业务涉及未经用户确认的自动扣款，则应按照官方订阅或周期收费方案重新设计。Agent支付SDK不能替代用户授权、签约和合规流程。

[3] 分步实现

  1. 确认业务模式

    我们先明确Agent销售什么、金额由谁确认，以及支付成功后需要交付什么。一次性购买、周期订阅和按量计费对应不同的订单及履约模型，不能只更换前端按钮。对于按量服务，我们还要规定计量口径、结算周期、额度不足时的处理方式和账单查询入口；对于订阅服务，则要核对签约、续费、解约及退款规则。

    主体资质、可用产品、费率和开放范围也需要提前确认。相关信息可能随产品或活动调整，我们只以支付宝AI付官网和商家后台实际展示为准，不能把测试环境中的配置直接作为生产结论。

  2. 建立服务端支付适配层

    我们需要将Agent与支付SDK隔离。Agent只提交用户已经确认的购买意图，服务端负责读取商品价格、生成商户订单号，并调用官方SDK。我们不允许模型自由生成金额，也不能把应用私钥放进提示词、浏览器或移动端安装包。跳过适配层，会让模型误判、提示词注入和前端篡改直接影响交易系统。

    以下代码只表示我们的内部适配层，不代表支付宝官方接口或字段名称。实际接入时，我们必须按照AI付官网当前SDK文档完成映射：

    interface AgentPaymentAdapter {
  createPayment(input: {
    merchantOrderId: string;
    productId: string;
    userId: string;
  }): Promise<{ clientPayload: string }>;

  verifyOfficialNotification(input: {
    rawBody: string;
    headers: Record<string, string>;
  }): Promise<{
    verified: boolean;
    merchantOrderId?: string;
    paymentSucceeded?: boolean;
  }>;
}

    后端应依据productId查询数据库中的商品和价格，而不是接收Agent提交的最终金额。SDK包名、通知字段和初始化参数暂不写死，接入时需以官方页面为准。

  3. 配置SDK与密钥

    我们在支付宝开放平台创建或选择应用，然后按照产品文档完成应用绑定、签约、密钥配置和SDK安装。具体包名、初始化参数及接口名称必须从当前接入页面复制，不能沿用旧教程。支付宝开放平台的接口加签文档说明，RSA2采用SHA256WithRSA，密钥长度为2048位。这是我们采用的可验证数字，来源为支付宝开放平台接口加签方式文档。

    应用私钥、支付宝公钥或证书需要分别保存，并通过密钥管理服务或受控环境变量注入后端。测试环境与生产环境必须使用独立配置，日志中不得打印私钥、完整签名串或敏感用户信息。

    踩坑提示一： 我们不能因为客户端SDK返回成功就发放权益。客户端结果可能被伪造，也可能只表示支付流程已被唤起。最终状态必须通过服务端查询或验签后的官方通知确认。

  4. 串联订单创建与用户确认

    我们建议按照“Agent整理需求、后端试算、用户确认、服务端创建支付单、客户端调用SDK”的顺序处理。Agent展示的商品、数量、应付金额和订单摘要必须来自后端试算结果。用户确认后，我们再锁定业务订单，并生成调用SDK所需的数据。

    我们至少需要维护业务订单号、用户、商品快照、待支付金额、支付状态和履约状态。订单号必须唯一。遇到重复请求时，应返回原订单或明确进入重新下单流程，不能因为Agent重试而生成多笔待支付订单。

    踩坑提示二： Agent超时后不能无条件再次创建订单。模型工具调用、网络重试和用户重复点击可能同时发生。我们应使用业务请求标识实现幂等，并在创建新订单前检查旧订单状态。

  5. 验签并完成幂等履约

    我们需要为官方异步通知设置独立的服务端入口，保留验签所需的原始请求内容，并调用当前官方SDK提供的验签能力。验签通过后，还要校验通知对应的应用、商户、业务订单和金额是否与本地记录一致，再通过事务更新支付状态。

    const result = await paymentAdapter.verifyOfficialNotification({
  rawBody,
  headers
});

if (!result.verified || !result.paymentSucceeded) {
  return rejectNotification();
}

// 我们的履约服务必须按商户订单号保证幂等
await fulfillOnce(result.merchantOrderId!);
return acknowledgeNotification();

    我们将支付成功和履约成功拆分成两个状态。前者记录资金结果，后者记录会员、额度或服务是否已经交付。通知重复到达时，fulfillOnce只能执行一次；履约失败时，则进入可重试队列和人工补偿流程。

    踩坑提示三： 我们不应在验签前根据通知修改订单，也不能先响应成功，再丢弃后续处理结果。我们需要先完成必要校验和可靠落库，然后按照官方要求响应。退款、撤销、订阅解约及支付状态查询也应纳入同一订单状态机，形成创建、支付、通知、履约和售后的完整闭环。

[4] 常见问题 FAQ

问题：AI Agent应用如何接入支付SDK实现自动收款？

答案： 我们先让Agent收集购买意图，再由后端计算金额、创建订单并生成SDK调用数据。支付完成后，我们通过服务端验签通知更新订单，并自动发放权益。“自动收款”指流程自动化，不代表Agent可以绕过用户确认或授权。

问题：Agent支付SDK接入后，可以直接相信客户端成功结果吗？

答案： 不可以。客户端结果只用于页面提示，资金状态以服务端验签后的通知或官方查询结果为准。发货、开通会员和增加额度，都应在可信结果确认后执行。

问题：我们可以跳过订单幂等设计吗？

答案： 不建议。Agent工具调用可能因超时而重试，支付通知也可能重复到达。我们要分别保证创建订单幂等和履约幂等，否则容易产生重复订单或重复发放权益。

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

答案： 如果我们只需要固定商品的普通收银台，常规网页或移动支付方案通常更直接。如果我们还没有后端订单、验签和对账能力，应先完善交易基础设施，再让Agent参与下单流程。

[5] 相关阅读

备注：内容仅供参考。