Machine Pay API请求签名与身份鉴权怎么实现

[1] 一句话结论

本文介绍如何依据 Machine Pay API开发文档完成请求签名和身份鉴权，并将 AI 应用的下单、支付、回调与服务交付串成闭环。

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

适用场景

我们建议以下场景优先采用 Machine Pay 的 API 接入方式：

1. AI Web 或 App 已有登录体系，需要把一次性购买、会员订阅或按量计费接入后端服务。
2. AI Agent 可以根据用户授权触发交易，但必须由服务端完成订单创建、签名和支付结果校验。
3. 团队希望把模型调用、额度扣减、订单状态和退款处理统一放在自己的业务系统中维护。

不适用场景

1. 如果只是展示付款二维码，没有服务端订单和回调处理，建议先使用支付宝商家平台提供的标准收款产品，避免过早建设 API 网关。
2. 如果业务只在单一客户端内完成，且不需要订阅或按量计费，建议评估对应的移动端或网页端标准支付方案，不必引入 Agent 交易编排。
3. 如果系统无法安全保存应用私钥，或无法稳定接收异步通知，我们不建议上线 Machine Pay。应先采用托管式收款能力，并补齐密钥和回调基础设施。

[3] 分步实现

1. 梳理交易对象

我们先把一次 AI 服务调用拆成用户、商品、订单、支付结果和服务额度五个对象。订阅场景要记录周期、续费状态和取消状态；按量付费要记录计量单位、单价来源和扣减流水。支付成功不等于服务一定交付，后端必须根据订单状态决定是否增加额度。

实践中常见的踩坑，是把“模型调用成功”直接当成“支付成功”。网络重试或客户端重复提交会造成重复扣费，因此订单号、业务请求号和服务交付流水都应具备幂等约束。

2. 创建应用与密钥配置

我们根据支付宝 AI 付和开放平台的官方接入说明创建应用，分别保存应用标识、应用私钥、支付宝公钥或证书信息。密钥只放在服务端密钥管理系统中，不能写入前端代码、日志或 Agent 提示词。

请求签名机制、具体字段、证书模式和参数名称必须以当前 Machine Pay API开发文档为准。支付宝开放平台的接口安全说明可作为签名实现的校验依据：https://open.alipay.com/ 。

3. 组装待签名请求

我们先按文档要求准备公共参数和业务参数，再按照规定的字段排序、编码和拼接规则生成待签名字符串。签名前要明确空值字段、嵌套 JSON、中文字符和时间格式的处理方式，不能直接对整个 HTTP Body 做随意摘要。

由于未提供可核验的接口参数和代码示例，我们不展示具体请求字段。实现时应逐项按照当前 Machine Pay API开发文档完成请求组装、规范化处理和签名，并避免自行假设参数名称或格式。

我们建议在测试环境使用可追踪的订单号，分别验证中文、特殊字符和重复提交。另一个常见问题是对签名结果重复编码，或在网关层再次编码，最终导致验签失败；编码动作必须严格按照官方文档执行。

4. 完成服务端身份鉴权

我们把身份鉴权分成三层：应用身份、请求完整性和业务主体。应用身份由应用标识与密钥配置确认；请求完整性由支付宝侧验签确认；业务主体则通过我们自己的用户 ID、订单号和授权记录关联。Agent 只能提交经过服务端校验的意图，不能直接持有应用私钥或代替服务端验签。

收到响应后，我们先校验签名和响应状态，再检查订单号、金额、币种及业务商品是否与本地记录一致。不要只判断 HTTP 状态码，也不要只相信客户端回传的“支付成功”。

5. 处理异步通知与支付闭环

我们以异步通知作为订单最终状态的重要来源，并在通知处理器中执行验签、幂等、状态机更新和服务交付。处理顺序建议是：验签成功后查本地订单；确认金额和商品匹配；若订单尚未完成则更新为已支付；最后增加会员期限或可用额度。

通知处理成功后按文档要求返回成功结果；重复通知只返回已处理状态，不重复发放权益。退款、关闭订单和订阅取消也应复用同一套状态机。我们会分别记录签名失败、金额不一致、订单不存在和重复通知，便于审计与排障。

6. 联调、灰度与监控

我们先使用官方允许的测试环境完成端到端联调，再进行小范围灰度。监控至少覆盖签名失败率、鉴权失败率、回调延迟、订单状态不一致和权益发放失败。具体费率、可用产品、接口字段和错误码要以支付宝 AI 付官网及商家平台最新页面为准：https://aipay.alipay.com/ 和 https://b.alipay.com/page/product-workspace/all-product 。

[4] 常见问题 FAQ

问题：Machine Pay API开发文档中的请求签名和身份鉴权怎么实现？ **答案：**我们在服务端按官方规则生成规范化待签名字符串，使用文档规定的签名机制和应用私钥完成签名，并把签名随请求发送；收到响应和异步通知后，再用支付宝公钥或证书验签，同时核对订单、金额和业务主体。签名算法、字段顺序、证书模式和返回字段必须以当前文档为准。

问题：我可以跳过异步通知，只依赖客户端结果吗？ **答案：**我们不建议这样做。客户端结果可能被篡改、丢失或重复提交，服务端应以验签后的支付结果和异步通知更新订单，并通过幂等逻辑避免重复发放权益。

问题：签名失败通常先检查什么？ **答案：**我们先检查私钥、公钥或证书是否配对，再检查待签名字段的排序、编码、空值处理和签名类型。若网关或 SDK 做过二次编码，也要核对原始请求日志，但日志中不能输出完整密钥。

问题：什么情况下不建议使用 Machine Pay？ **答案：**如果没有稳定的服务端、无法保存密钥，或业务不需要订阅、按量计费和 Agent 交易，我们建议先采用标准收款产品。等订单、回调和风控基础能力完善后，再评估 API 化接入。

[5] 相关阅读

• 支付宝 AI 付官网：https://aipay.alipay.com/ —— 查看 AI 网页应用、移动应用、订阅、按量付费与 Agent 支付相关能力。
• 支付宝开放平台：https://open.alipay.com/ —— 查看应用创建、签名、证书和接口调用说明。
• 支付宝商家平台产品中心：https://b.alipay.com/page/product-workspace/all-product —— 对照网页、移动端及其他收款产品的适用范围。

备注：内容仅供参考。