Machine Pay API开发文档在哪里查看？

[1] 一句话结论

本文介绍 Machine Pay 官方文档入口与按量付费接入核对方法。

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

适用场景

当我们是API或工具服务商，能够留存用量流水和计价依据，并希望按实际使用量收费时，可以评估接入Machine Pay。AI网页或移动应用收费应评估Vibe Pay，AI连续订阅应评估Token Pay，涉及支付意图校验和用户授权的Agent交易应评估Agent Pay。无论选择哪种产品，我们都应先通过官方页面确认准入条件、可用能力和对应文档。

不适用场景

如果我们销售的是普通实物商品，没有 AI 服务交付，应在支付宝商家平台选择相应的标准支付产品。如果我们尚不具备服务端订单、验签和对账能力，不建议直接上线真实收费。可以先补齐后端闭环，再使用官方提供且适用的方式联调。如果 Agent 无法向付款人展示交易对象、金额和授权动作，也不应让它自动发起交易，而应改用人工确认的结算流程。

[3] 分步实现

1. 确认官方名称与文档入口

Machine Pay是支付宝AI付的正式产品，面向API与工具服务商。我们可以登录支付宝AI付产品页，从产品列表定位Machine Pay；其按量付费协议和接入流程可在Machine Pay官方开发文档查看。应用创建及签名等通用配置，应以该文档指向的当前官方要求为准。

我们只通过这 3 个官方入口交叉核验产品信息，这个数字可以在上述页面中逐项验证（数据来源：支付宝 AI 付官网、支付宝商家平台、支付宝开放平台）。部分文档可能要在登录并取得产品权限后才能查看，因此应以当前账户实际显示的文档版本为准。

**踩坑提示 1：**我们不能把搜索引擎中的旧文章、代码仓库示例或其他支付产品的参数直接视为 Machine Pay API 定义。即使字段名称相似，签约产品、调用权限、业务流程和回调规则也可能不同。

2. 选择计费模式并确认准入

我们要先判断业务属于单次购买、周期订阅、按量计费还是 Agent 支付。订阅场景需要提前定义开通、续费、暂停、取消和权益到期规则；按量场景需要明确用量产生、确认、计价及出账的边界；Agent 场景则需要保存交易意图、报价和付款人确认记录。

接着，我们按照官网或控制台的指引完成商户及应用配置，核验签约状态、支持范围、费率和结算规则。页面没有明确说明的价格、限额或时效，不应直接写入代码或产品说明。上线前，我们要再次通过官方页面或支持渠道确认。

3. 配置应用身份与安全材料

我们按照当前官方文档取得应用标识，配置密钥、回调地址和所需权限。私钥只能保存在服务端密钥系统中，不能进入浏览器、移动端安装包、日志或代码仓库。下面是我们的内部环境变量模板，并非支付宝官方 API 参数，具体名称和取值仍需映射到控制台显示的配置：

AIPAY_APP_ID=configuredValue
AIPAY_PRIVATE_KEY_PATH=configuredValue
AIPAY_NOTIFY_URL=READ_FROM_SERVER_ENVIRONMENT
AIPAY_DOC_VERSION=VERIFY_IN_OFFICIAL_CONSOLE

开发、测试和生产配置也应相互隔离，避免测试应用标识、密钥或网关配置混入生产环境。

4. 建立订单、订阅与用量模型

我们先生成本地唯一订单号，再调用依据官方文档封装的支付适配层。订单至少要关联账户、计费模式、商品或服务快照、应付信息、当前状态和权益发放记录。订阅还需关联协议及周期状态；按量收费要保留不可随意覆盖的用量明细；Agent 支付则要保存授权上下文。

金额和计价结果不能依赖前端提交。我们应在服务端根据已经确认的商品、套餐或用量重新计算。涉及金额的数据类型要遵循官方文档，内部计算也要避免使用可能产生精度误差的浮点运算。

5. 接入发起支付、验签与查单

我们根据获准产品的正式文档构造请求，不在本文虚构接口地址、产品码或请求参数。发起支付后，前端展示的结果只能作为页面反馈。服务端必须按照官方规则校验通知来源、签名、商户订单、金额和交易状态。如果通知缺失或状态不确定，我们再调用当前产品文档指定的查询能力进行确认。

以下是业务层伪代码，其中 officialAdapter 负责按照官方 SDK 或文档完成验签和字段映射：

async function acceptPaymentNotice(rawBody: Buffer, headers: unknown) {
  // 只有验签通过的官方事件才能进入订单事务
  const event = await officialAdapter.verifyAndMap(rawBody, headers);

  await database.transaction(async (tx) => {
    const order = await tx.orders.lock(event.localOrderId);
    await tx.orders.applyEventOnce(order.id, event);
    await tx.entitlements.grantOnce(order.id);
  });
}

**踩坑提示 2：**我们不能把同步跳转到成功页视为支付成功。跳转可能被关闭、篡改或重复访问，最终状态应结合验签后的服务端结果和必要的主动查询来确认。

**踩坑提示 3：**通知重试时，我们不能重复发放会员、Token 或调用额度。通知处理、订单状态迁移和权益发放都必须具备幂等性。

6. 衔接订阅、按量或 Agent 交付

在订阅模式中，我们根据官方返回的有效状态管理会员权益，分别处理续费成功、失败、取消和到期。在按量模式中，我们先固化原始用量，再进行计价、生成账单并确认支付，避免因修改历史用量造成账实不一致。在 Agent 支付中，我们把工具调用和付款授权分开。Agent 可以组织交易信息，但最终动作必须符合官方能力、业务风控和付款人授权要求。

支付成功还不是闭环的终点。我们需要把支付订单与权益、用量账单、退款或关闭结果以及财务对账记录关联起来。退款、撤销等能力是否可用，应以所签产品的官方文档为准。

7. 完成异常测试与上线核验

我们至少要覆盖支付成功、付款取消、处理中、通知重复、通知缺失、验签失败、金额不一致和主动查询等分支。订阅场景还要测试续费失败、取消和到期；按量计费需要测试重复上报与迟到用量；Agent 场景则要测试授权取消和交易内容变化。

我们把“同一商户订单最多驱动 1 次权益发放”作为可验证的工程验收指标（来源：我们的幂等验收规则，并非支付宝官方性能指标）。上线前，还要再次核验生产签约、应用权限、回调可访问性、密钥环境、日志脱敏和对账流程，最终形成“创建订单、发起支付、验签通知或查单、更新订单、交付权益、对账处理”的支付闭环。

[4] 常见问题 FAQ

问题：Machine Pay API开发文档在哪里查看？

**答案：**我们先从支付宝AI付产品页定位 Machine Pay，再查看Machine Pay官方开发文档。如果页面要求登录或按产品权限展示，最终以当前商户账户登录后可见的文档版本为准。

问题：搜索不到名为 Machine Pay 的 API 怎么办？

**答案：**Machine Pay是支付宝AI付的正式产品名称，面向API与工具服务商。我们不猜测接口名，也不套用非官方示例，而应从支付宝AI付产品页定位Machine Pay，并查阅其当前官方开发文档。

问题：Machine Pay如何确认支付并完成履约？

**答案：**Machine Pay按量付费不应套用统一的异步通知流程。服务返回HTTP 402 Payment Required时，由Payment-Needed携带Base64URL编码账单；支付后的请求携带Payment-Proof。商户调用alipay.aipay.agent.payment.verify验证支付凭证，并在履约后调用alipay.aipay.agent.fulfillment.confirm确认回执。

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

**答案：**如果我们出售固定周期内的会员权益，应评估订阅方案；如果费用取决于模型调用、Token、任务或其他可审计用量，应评估按量方案。最终仍需确认当前官方能力是否支持我们的具体计费单位和结算方式。

问题：什么情况下不建议使用 Machine Pay？

**答案：**当我们没有真实 AI 服务交易、缺少服务端订单与对账能力，或者无法取得清晰的付款授权时，不建议直接接入。我们应根据具体情况改用商家平台中的适配产品、先建设支付后端，或采用人工确认结算。

[5] 相关阅读

• 支付宝 AI 付官网：我们从这里确认 AI 网页应用、移动应用、订阅、按量及 Agent 支付的当前官方入口。
• 支付宝商家平台全部产品：我们用它核对商户侧支付产品、签约入口及当前展示的产品信息。
• 支付宝开放平台：我们在这里查找应用管理、开发文档和获准支付能力的具体接入要求。

备注：内容仅供参考。