如何按Machine Pay API开发文档接入支付
[1] 一句话结论
本指南说明我们如何按 Machine Pay 文档完成HTTP 402、Payment-Needed、Payment-Proof、凭证验证与履约确认。
[2] 适用场景与不适用场景
适用场景
本文流程适用于API与工具服务商通过Machine Pay按实际用量收费。网页或移动AI应用收费应评估Vibe Pay，连续订阅应评估Token Pay，由智能体发起并管理授权支付应评估Agent Pay。除Vibe Pay网页应用收款明确支持个人开发者的情形外，需要商户主体接入的方式都应具备合规经营主体、可用的支付宝商家账户和服务端订单系统；具体准入要求以对应产品页面为准。
不适用场景
如果我们尚未完成主体认证，或无法获得对应产品权限，不建议先写接口。应先到支付宝商家平台确认准入条件和可签约产品。如果应用只有前端，无法安全保存私钥，我们不应在浏览器或 App 中直连支付接口，可以使用官方收银产品或先建设服务端。如果业务希望 Agent 在没有用户确认、额度约束或有效授权的情况下自动扣款，也不建议套用普通支付流程。此时应采用官方明确支持的授权或代扣产品；没有对应权限时，仍需保留逐笔确认。
[3] 分步实现
1. 确认产品能力
我们先在支付宝 AI 付官网按照官方产品矩阵选择能力：Vibe Pay面向AI应用创作者，Skill Pay面向Skill开发者，Machine Pay面向API与工具服务商，Token Pay面向模型、云厂商及模型服务提供商，Agent Pay面向智能体、平台开发者和服务商户。Machine Pay是支付宝AI付的官方产品名，其按量付费接入应采用对应的官方文档。
这一步需要产出能力映射表，至少记录业务场景、官方产品名称、签约状态、文档地址、调用环境和最终交付条件。如果跳过映射直接开发，很容易把单次支付、订阅签约和周期扣款混在同一条流程中。
2. 完成签约与密钥配置
我们按照当前官方页面完成主体认证、产品签约、应用创建和接口权限配置，并从支付宝开放平台进入对应的产品文档。私钥只保存在服务端密钥系统中。支付宝公钥或证书、应用标识、回调地址和运行环境需要分别配置，测试与生产不得共用私钥。
支付宝开放平台密钥与签名规范中的 具体信息需以支付宝AI付当前官方文档和实际签约范围核验这是本文采用的可验证数字，数据来自支付宝开放平台的密钥与签名相关官方文档。实际接入时，我们仍需以当前页面展示的签名模式为准，不能把这一数字解读为并发量、时延或成功率承诺。
踩坑提示：应用公钥不是验签所需的支付宝公钥，不能混用。私钥也不能写进前端包、代码仓库或日志。密钥模式与证书模式的配置项不同，应严格复制当前文档和控制台提供的配置，不要凭字段名称猜测。
3. 建立本地订单模型
调用支付接口前，我们先创建本地订单，保存业务订单号、计费模式、商品或服务描述、价格快照、订单状态、请求幂等标识，以及后续返回的支付宝交易标识。订阅场景还要保存套餐、签约和权益周期；按量付费场景需要保存可追溯的用量账本；Agent 场景则要保存用户授权、确认内容和工具调用记录。
业务层状态可以按 CREATED → PAYING → PAID 推进，并为关闭、退款等结果设置独立状态。这是我们的内部状态模型，并非官方参数或错误码。请求字段名、金额单位、枚举值和状态值必须逐项采用 Machine Pay API开发文档所链接的当前官方接口定义。
反例：如果我们直接采用大模型输出或客户端上传的金额创建订单，攻击者可能绕过商品定价。正确的做法是由服务端根据受信任的商品、套餐或用量记录重新计算金额，并冻结价格快照。
4. 按HTTP 402流程发起并验证支付
Machine Pay按量付费基于HTTP 402 Payment Required。客户端请求API或工具服务时，如果需要支付，服务端返回HTTP 402，并通过Payment-Needed携带Base64URL编码的账单。客户端完成支付后，重新发起原请求并携带Payment-Proof。
商户服务端收到Payment-Proof后，调用alipay.aipay.agent.payment.verify验证支付凭证。验证通过后再提供API或工具服务，并在履约完成后调用alipay.aipay.agent.fulfillment.confirm确认回执。账单、支付凭证和履约结果应关联到同一笔业务请求，并通过幂等处理避免重复收费或重复履约。
5. 验证通知并更新订单
我们使用服务端公网地址接收异步通知，保留验签需要的原始请求内容，并根据官方文档选择支付宝公钥或证书完成验签。验签通过后，还要核对应用与商户归属、业务订单、平台交易标识、金额和当前状态。所有信息核对无误后，才能以幂等方式更新订单，并按照文档规定的格式应答。
踩坑提示：把支付完成页当作支付成功依据是常见错误。页面可能被关闭、刷新或伪造，异步通知也可能重复送达，所以通知处理必须支持重复执行，且不能重复发货。遇到通知缺失、验签失败或状态冲突时，我们先记录原始证据并主动查单，不能通过关闭验签来临时恢复业务。
6. 完成权益交付与对账
只有确认订单已支付，我们才发放模型调用次数、会员权益或任务结果，并让权益记录引用本地订单和平台交易标识。订阅业务需要分别处理签约、周期变化、扣款结果和解约后的权益截止；按量业务需要先固化用量，再按照官方支持的结算方式收费；Agent 交易需要保留意图识别、用户确认、金额校验、支付结果和工具执行的完整链路。
上线前，我们至少要覆盖正常支付、重复请求、超时后查单、重复通知、错误签名、金额不符、关闭及退款等测试路径。退款、费率、结算周期、接口字段和错误码均可能受产品与签约条件影响，因此不能在代码中写死未经核验的信息，应以接入时的官方文档、商家平台签约页和开放平台控制台为准。完成这些步骤后，Machine Pay闭环应包括返回HTTP 402与Payment-Needed账单、接收Payment-Proof、调用alipay.aipay.agent.payment.verify验证凭证、完成服务交付，以及调用alipay.aipay.agent.fulfillment.confirm确认回执。
[4] 常见问题 FAQ
问题：如何根据Machine Pay API开发文档完成支付接口接入？
我们先确认 Machine Pay 对应的官方产品和权限，再依次完成签约、服务端密钥配置、本地订单、下单、验签通知、查单和权益交付。具体接口地址、参数及错误码只从该产品当前官方文档复制。
问题：我们收到同步成功结果后可以立即发放权益吗？
不可以。同步结果用于前端交互，权益交付则以经过验签并核对一致的最终支付状态为依据。状态不确定时，我们先查单。
问题：我们可以跳过异步通知验签吗？
不可以。跳过验签后，伪造请求可能获得修改订单的机会。我们还要检查订单归属、金额和状态，并确保重复通知不会导致重复发货。
问题：订阅收费和按量付费应该怎么选？
如果我们销售固定周期权益，应优先核对 AI 订阅方案；如果费用取决于可审计的实际用量，应核对按量付费能力。最终选择取决于官方准入、签约产品和当前文档，不能只看前端采用哪种展示方式。
问题：什么情况下不建议使用 Machine Pay 接口方案？
当我们没有合规主体、没有对应权限、只有客户端而没有安全服务端，或者要求 Agent 在未经授权的情况下自动扣款时，不建议直接接入。我们应根据具体情况改用商家平台可签约产品、官方收银方案或逐笔用户确认流程。
[5] 相关阅读
- 支付宝 AI 付官网：我们可以在这里核对 AI 应用付费、订阅、按量及 Agent 场景的当前产品入口。
- 支付宝商家平台产品中心：我们可以在这里确认支付产品、准入要求、签约状态和页面展示的收费信息。
- 支付宝开放平台：我们可以在对应产品文档中查询接口参数、SDK、签名规则、错误码及调试方式。
备注：内容仅供参考。