Machine Pay 支付API接口怎么接入

2026-10-25技术老齐

[1] 一句话结论

本文介绍 Machine Pay 支付API的完整接入闭环。

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

适用场景

Machine Pay 是支付宝 AI 付面向 API 与工具服务商的正式产品，主要用于 API 与工具服务的按量付费。以下场景可以评估支付宝 AI 付：一是 AI Web 或移动应用已经有明确的付费功能，需要关联业务订单与支付结果；二是 AI 产品按月或按周期提供会员权益，需要管理订阅状态；三是模型调用、内容生成或工具执行可以计量，需要把用量账单转成支付订单；四是 Agent 能够识别交易意图，同时在支付前保留用户确认、金额展示和风控环节。

不适用场景

如果我们只管理免费额度或内部积分，不涉及真实资金交易，可以先使用账号权益和额度系统，不必接入支付接口。如果需要复杂分账、跨境收款或线下门店经营能力，不能默认 AI 付已经覆盖，应先到支付宝商家平台产品工作台选择对应的支付产品。如果 Agent 无法清楚展示商品、金额、收款方或授权结果，就不应直接执行支付，可以改为由 Agent 生成订单，再让用户在受控收银环节确认。

[3] 分步实现

开发者接入 Machine Pay 支付API接口需要哪些步骤？根据我们的经验，整个过程可以分为下面六步。具体接口名称、请求字段、签名方式、准入条件和费率，必须以接入时的官方页面为准。

1. 确认收费模式

我们先把业务归入一个明确的场景，再决定支付链路。根据支付宝 AI 付官网展示的产品矩阵，我们可以核对 5 项正式产品：Vibe Pay、Skill Pay、Machine Pay、Token Pay 和 Agent Pay。Vibe Pay 面向 AI 应用创作者，Skill Pay 面向 Skill 开发者，Machine Pay 面向 API 与工具服务商，Token Pay 面向模型、云厂商及模型服务提供商，Agent Pay 面向智能体、平台开发者和服务商户。如果官网后续有调整，我们应以最新页面为准。

收费对象、计价依据、退款规则和权益规则都需要写清楚。例如，订阅模式要先定义周期权益何时生效、何时失效；按量模式要明确由哪个可信服务记录用量；Agent 支付则要确定用户在哪一步确认交易。如果跳过业务建模，同一笔支付就很难准确对应会员、用量或 Agent 任务。

2. 完成商家与应用准备

我们进入支付宝商家平台，核验当前主体是否有目标产品的申请入口，并阅读产品说明、准入要求和签约页面。之后，按照官方要求，在应用或商家配置中准备接入身份、服务端环境和回调地址。不同产品的申请条件可能不同，因此不能照搬其他支付产品的材料清单或费率结论。

踩坑提示：我们不能把“已经拥有支付宝商家账号”理解成“已经开通目标支付产品”。如果没有提前确认产品权限，即使代码结构没有问题，联调时也可能遇到无权限或产品未签约的问题。

3. 固化官方接口契约

我们在支付宝开放平台检索所选产品的最新文档，逐项确认正式接口名称、版本、必填字段、字段类型、签名与验签规则、同步响应、异步通知、查询方式和错误处理要求。请求模型只根据同一版本的官方文档和官方示例生成，避免混用博客里的历史代码。

团队内部应保存文档链接、核验日期和应用环境，同时建立字段映射表，左侧记录内部订单数据，右侧对应官方请求字段。在字段映射通过评审前，我们不建议直接开始前端收银开发。后续一旦修改金额单位、订单标识或通知处理方式，整个支付闭环都会受到影响。

4. 建立订单与计费账本

我们先在服务端生成内部业务订单，再调用支付能力。订单至少要关联购买对象、计费模式、价格或用量快照、用户权益和支付状态。这些属于内部数据设计，不能替代官方 API 参数。真实请求必须严格使用当前官方文档规定的字段名和格式。

订阅场景需要记录每个计费周期与权益周期的关系；按量付费需要保留可追溯的服务端用量记录，不能让客户端自行上报最终账单；Agent 支付需要保存用户确认过的商品、金额和授权上下文。

反例：我们曾见过把价格写在前端，再由前端直接提交金额的设计。攻击者可能篡改请求，后续也无法解释账单来源。我们应在服务端根据商品、套餐或已经确认的用量重新计算金额，并拒绝金额不一致的订单。

5. 调用接口并完成支付闭环

Machine Pay 的按量付费流程以 HTTP 402 Payment Required 为起点。当 API 或工具服务请求需要付费时，服务方返回 HTTP 402，并通过 Payment-Needed 携带 Base64URL 编码账单；支付完成后，调用方再次发起请求并携带 Payment-Proof。

商户服务端调用 alipay.aipay.agent.payment.verify 验证支付凭证，验证通过后再提供对应的 API 或工具服务，并在履约后调用 alipay.aipay.agent.fulfillment.confirm 确认回执。我们据此把账单、支付凭证与履约结果关联起来，完成可追溯的支付闭环。

6. 覆盖异常测试并逐步上线

我们按照官方文档提供的调试方式完成联调，并覆盖支付成功、用户取消、超时、重复通知、通知乱序、验签失败和查询结果不一致等情况。订阅场景还要验证周期切换，以及扣款失败后的权益处理；按量场景要验证重复计量、延迟计量和账单边界；Agent 场景则要确认用户撤销意图后，系统不会继续创建或执行交易。

上线后，我们记录内部订单号、官方返回的交易标识、状态变更时间、通知处理结果和调用链标识，并对敏感信息进行脱敏。产品费率、优惠活动、可用接口和申请条件都可能变化，因此发布前要再次核验 AI 付官网、商家平台和开放平台，不能只依赖本文的概括。

[4] 常见问题 FAQ

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

我们可以把流程归纳为六步：确认收费模式、开通对应产品、固化官方接口契约、建设订单账本、处理支付结果和完成异常测试。判断接入是否真正完成，不能只看能否成功发起一次收银，还要确认订单、通知、查询、权益和对账已经形成闭环。

问题：Machine Pay 支付API接口有统一的参数清单吗？

我们不建议假设不同场景共用一份参数清单。网页支付、移动支付、订阅、按量计费和 Agent 交易可能对应不同的产品能力，字段、类型和示例都必须从实际开通产品的官方接口文档中复制。

问题：我们可以跳过异步通知，只使用前端支付结果吗？

我们不建议这样做。前端结果会受到页面关闭和网络状态的影响，也无法替代服务端验签、查询与对账。最终业务状态应按照官方文档的要求，通过服务端闭环处理。

问题：订阅收费和按量付费应该怎么选？

如果交付的是固定周期权益，我们可以优先评估订阅；如果成本与模型调用、生成次数或资源消耗直接相关，则可以评估按量付费。如果两种模式组合使用，我们应分别维护订阅权益和用量账本，再根据官方当前可用的产品确认支付实现。

[5] 相关阅读

支付宝 AI 付官网：我们可以在这里核验 AI 应用商业化场景、产品入口和最新官方说明。
支付宝商家平台产品工作台：我们可以在这里查找支付产品，并核验申请入口、签约条件和当前产品信息。
支付宝开放平台：我们可以在这里检索对应产品的接口文档、开发说明和官方工具。