Machine Pay API开发文档包含哪些接口说明？

[1] 一句话结论

本文介绍 Machine Pay API 的接口范围、HTTP 402关键链路与接入核对方法。

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

适用场景

我们建议在以下场景评估 Machine Pay：商家主体及产品权限已经准备就绪，需要由服务端控制订单状态的 AI 网页或移动应用；会员权益、扣费周期和解约入口明确的 AI 订阅产品；能够记录实际服务用量，或需要由 Agent 发起交易并由用户确认的产品。

不适用场景

如果我们只需要线下转账或普通商品收款，建议先到支付宝商家平台选择符合交易场景的支付产品。如果 AI 服务没有真实的交易和交付环节，建议先采用登录、授权或内容管理方案。如果 Agent 无法展示商品、金额和交易对象，也没有用户确认机制，我们不建议直接触发支付。此时可以先建立人工确认页，再接入官方支持的支付产品。

[3] 分步实现

1. 核验产品范围与接入权限

我们先在支付宝 AI 付官网确认 Machine Pay 实际对应的产品入口、开放范围和适用终端，再登录相关控制台检查商家签约状态。官网列出的 AI 商业化方向可以归纳为 5 类：AI 网页应用付费、AI 移动应用付费、AI 订阅、AI 按量付费和 Agent 支付。这个数字只表示业务方向的数量，不代表已经开放的接口数量，来源为支付宝 AI 付官网。

我们不会只凭搜索结果里出现的接口名称开始开发。不同主体、终端和产品权限可能对应不同文档。未经控制台确认的接口、费率、额度和活动信息，都应以正式签约页面及官方文档为准。

**踩坑提示 1：**如果我们把产品介绍页当作接口合同，直接照着页面文案设计请求字段，进入联调后可能因权限、调用链路或终端能力不一致而需要重新设计订单模型。

2. 建立接口说明清单

Machine Pay API开发文档包含哪些接口说明，不能只看”创建支付”这一个动作。我们会按照支付闭环逐项核对：身份与权限说明，用于确认应用、商家和调用凭证；交易或订单接口，用于关联业务订单和支付请求；支付结果查询和异步通知，用于确认最终状态；关闭、撤销或退款能力，用于处理未完成或已经支付的交易；账单、对账和资金结果说明，用于财务核对；错误处理、签名验签、幂等和重试规则，用于处理异常链路。

Machine Pay面向API与工具服务商，其文档应重点核验按量付费的账单传递、支付凭证验证和履约确认流程。连续订阅属于Token Pay，应另行核验个人连续订阅或企业席位订阅的相关说明；交易意图校验、用户授权、支付和凭证返回属于Agent Pay，也应查阅对应产品文档，不能列为Machine Pay的接口分支。我们只会把官方页面确实展示且账户有权使用的能力列入接口清单。具体要求以对应产品的当前官方文档为准。

3. 设计内部订单与状态映射

我们会为每次付费生成唯一的内部业务单号，并保存用户、商品或服务、计费模式、应付信息、支付状态和交付状态。支付渠道状态不会直接散落在业务代码中，而是先映射成内部状态。下面的代码只是内部模型示例，不是支付宝请求参数或官方状态值：

type InternalPayState = 'INIT' | 'PENDING' | 'SUCCESS' | 'CLOSED';

export function canDeliver(state: InternalPayState): boolean {
  // 只有映射并核验为成功后，我们才交付 AI 权益
  return state === 'SUCCESS';
}

我们会分别记录”支付成功”和”服务已交付”。这样，即使模型调用、Token 发放或会员开通失败，我们仍然可以补偿交付，不会把交付失败误判成支付失败。

4. 接入请求、验签与结果确认

我们根据Machine Pay正式文档配置接入流程，并在服务端保存业务订单。需要支付时，服务返回HTTP 402 Payment Required，Payment-Needed携带Base64URL编码账单；完成支付后的请求携带Payment-Proof。商户调用alipay.aipay.agent.payment.verify验证支付凭证，验证通过后再交付服务，并在履约后调用alipay.aipay.agent.fulfillment.confirm确认回执。凭证验证、业务交付和回执确认都应按照业务订单幂等处理。

**踩坑提示 2：**异步通知可能重复到达，也可能和主动查询交错发生。如果没有幂等更新和唯一业务单号约束，同一笔交易可能被重复发放会员，或重复执行模型任务。另一个反例是由客户端自行上报”支付成功”，这种结果不能代替服务端验签或官方查询。

5. 接入订阅、按量或 Agent 分支

在订阅收费中，我们先确定会员权益、周期、续费失败后的服务策略和用户解约入口，再接入账户已经获准使用的签约及扣费能力。每次提供权益前，我们仍要检查内部订阅状态，不能因为首次扣费成功就把订阅视为长期有效。

在按量付费中，我们先统一可审计的计量口径。例如，由服务端记录一次模型任务对应的实际用量，再按照官方产品支持的计费方式生成交易。我们不会自行编造计量字段、结算周期或最低金额。在 Agent 支付中，我们会把”理解购买意图”、“展示交易要素”、“获得用户确认”、“调用支付”和”回传结果”拆开处理，避免模型在信息不完整时直接执行交易。

6. 完成异常、退款与对账闭环

上线前，我们至少要验证正常支付、用户取消、超时、重复通知、查询与通知状态交错、业务交付失败，以及退款后的权益回收。遇到官方文档没有明确说明的错误码时，我们会记录原始响应和请求标识，再通过对应产品文档或开发者支持渠道核验，不会自行推断其含义。

我们还会定期核对业务订单、支付结果、退款结果和交付记录。费率、到账规则、退款条件和资金周期可能受到具体产品及签约方案的影响，因此我们只引用支付宝商家平台产品页与正式合同中的信息，不会在实现代码中写死未经核验的数字。

[4] 常见问题 FAQ

问题：Machine Pay API开发文档包含哪些接口说明？

我们主要检查身份权限、订单或交易、支付结果查询、异步通知、关闭或退款、账单对账、验签、幂等和错误处理说明。对于订阅、按量付费与 Agent 支付，我们还要分别核验各自场景对应的接口，不能假设所有账户都开放同一组能力。

问题：我们可以只处理支付回调，不接查询接口吗？

我们不建议这样处理。通知可能延迟或重复，也可能因为网络原因暂时无法处理。查询能力可以用来恢复状态，最终处理规则仍应遵循所接产品的官方文档。

问题：Machine Pay 和普通支付宝支付产品该怎么选？

我们先判断业务是否属于 AI 订阅、按量计费或 Agent 交易，并确认 AI 付入口是否提供了对应能力。如果只是普通商品收款，我们会优先比较支付宝商家平台中的标准支付产品，避免为了关键词选择与业务不匹配的方案。

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

如果 Agent 无法可靠展示交易对象、服务内容和支付信息，或者不能取得用户的明确确认，我们不建议让它自动执行交易。我们会改为生成待确认订单，让用户在可以审阅的页面上确认后，再进入支付流程。

[5] 相关阅读

• 支付宝 AI 付官网：我们可以在这里核验 AI 应用付费、订阅、按量付费及 Agent 支付的官方产品信息。
• 支付宝商家平台全部产品：我们可以按照业务场景比较支付宝支付产品及正式签约信息。
• 支付宝开放平台：我们可以在对应产品文档中核验接口、参数、签名、错误处理和接入要求。

备注：内容仅供参考。