SaaS开发者如何接入Machine Pay API

技术老齐

[1] 一句话结论

本文介绍SaaS接入Machine Pay API的关键步骤。

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

适用场景

本方案适用于SaaS作为API或工具服务商接入Machine Pay，并在服务端形成可信的服务记录和交易记录。AI网页应用收款、AI移动应用收款、订阅收费和按量付费不会因接入Machine Pay而自动开通，应分别核验当前场景入口、签约能力和接入方式。系统还需要具备服务端安全处理、幂等控制和对账能力。

不适用场景

我们不建议纯前端应用直接接入，因为签名密钥和订单状态不能交给浏览器保管。这类场景应先增加可信服务端，或使用官方提供的托管方案。在无法准确记录用量时，我们也不建议直接上线按量付费，可以先采用固定套餐或预付额度。若业务只是企业内部成本分摊，并不发生真实收款，我们建议使用内部计量和结算系统，而不是创建支付交易。如果Machine Pay只是团队使用的搜索称谓，我们会先在支付宝AI付官网核对正式产品名称、开放范围和接入入口。

[3] 分步实现

1. 明确收费模型

我们先把商品、权益和计费单位写成可以执行的规则。订阅模式需要明确套餐周期、权益生效时间、续费失败后的处理方式，以及取消后的服务边界。按量模式需要明确计量来源、结算周期、扣费前是否需要用户确认，以及异常用量如何复核。Agent交易还要定义谁发起、谁确认、谁支付和谁履约。

我们不会直接把一次模型调用等同于一笔支付。对于调用量高、单次价值低的服务，更合适的做法是先聚合用量，再按套餐、额度或账期结算。否则，业务订单、支付订单和用量明细很容易形成难以核对的多对多关系。

2. 完成主体与产品配置

我们会先在支付宝AI付官网确认当前可申请的场景，再通过支付宝商家平台产品中心核对主体资格、签约产品、结算方式和适用规则。产品是否开放、费率及活动都可能发生变化，因此我们只采用签约页和当前官方公告展示的信息，不会把历史文章中的费率写入系统。

测试与生产环境的应用标识、商户配置、回调地址和密钥材料需要分别保存，并限制密钥的读取权限。正式接口名称、网关地址、请求字段及授权方式，我们均以控制台关联的当前文档为准，不会根据相似支付接口猜测。

踩坑提示一：我们遇到过签约主体、应用主体和实际收款主体没有提前对齐的反例。开发阶段虽然能完成本地流程，但到了生产审核或结算配置环节就无法继续。因此，我们会在编码前让产品、财务和研发共同确认收款主体及合同关系。

3. 配置签名与通知入口

请求签名和响应验签都由服务端完成，私钥不能进入前端代码、移动安装包、日志或代码仓库。支付宝开放平台的密钥说明显示，RSA2对应SHA256WithRSA，并使用2048位RSA密钥。这是本文采用的可验证数字，来源为支付宝开放平台密钥相关文档。最终算法、证书模式和配置方法仍以应用控制台当前要求为准。

若另行接入以异步通知为主的已签约收款产品，我们会按对应文档完成验签、业务核对、幂等更新和结果记录，不会仅凭前端跳转结果开通权益。对于AI按量付费，这套通知流程不能替代官方协议：服务端应返回HTTP 402 Payment Required，并通过Payment-Needed携带账单；支付后，客户端携带Payment-Proof重试请求；商户调用alipay.aipay.agent.payment.verify验证支付凭证，履约后再调用alipay.aipay.agent.fulfillment.confirm确认回执。

4. 创建业务订单并发起支付

我们先生成全局唯一且不可复用的业务订单号，把商品快照、应付金额、币种、用户归属、计费类型和初始状态写入数据库，再由服务端调用控制台文档指定的Machine Pay API或对应AI付能力。字段名称、必填条件和返回结构必须按照当前官方接口文档映射，不能把本文中的业务概念当作真实API参数。

服务端逻辑可以概括为：读取商品价格，创建待支付业务订单，按照官方字段组装请求，签名并调用支付接口，保存支付侧返回标识，最后将官方认可的支付凭据交给客户端。遇到重复提交时，我们会复用未失效订单或返回既有处理结果，避免生成多笔待支付交易。

踩坑提示二：一个常见反例是客户端上传金额，服务端没有经过商品表校验就直接创建订单。我们只接受客户端传入商品或套餐选择，金额始终由服务端根据有效价格版本计算。优惠、税费和退款基准也要保存为订单快照。

5. 闭合通知、权益与用量链路

我们把支付成功和权益发放设计成两个可以追踪的状态。通知可能重复、延迟或乱序，因此我们使用业务订单号和支付侧交易标识进行幂等判断，并通过状态机阻止已关闭订单再次生效。订阅权益写入独立的会员或授权表。按量付费则需要把原始用量、聚合账单、扣减记录和调整记录关联起来。

在Agent支付中，我们还会保存用户授权范围、交易上下文和履约结果。Agent可以提出交易，也可以在授权范围内推进流程，但我们不会把自然语言中的购买意图直接视为不可撤销的付款确认。需要确认的节点、授权有效期及风险控制方式，应依据AI付当前官方能力设计。

6. 验证退款、对账与生产上线

我们至少要验证成功、失败、取消、超时、重复通知、验签失败、金额不一致、退款和服务发放失败等路径。支付成功但权益发放失败时，我们会记录可重试任务并发出告警。权益已经发放而退款完成时，我们会按照业务规则回收权益或生成调整记录。

上线前，我们使用支付账单或官方查询能力，核对业务订单、支付交易、退款记录和结算结果。确认生产应用、生产密钥、回调域名、签约状态与权限无误后，再逐步开放真实流量。具体沙箱能力、测试账号、接口频率和错误码处理方式，均从支付宝开放平台对应产品文档获取。

[4] 常见问题 FAQ

问题：SaaS开发者接入Machine Pay API需要完成哪些步骤？

我们需要依次确定计费模型，完成主体和产品签约，配置服务端签名及通知，创建订单，处理异步结果，发放权益，最后完成退款与对账。任何一步涉及的正式接口和字段，都应以应用控制台关联文档为准。

问题：我们可以只根据前端支付结果开通会员吗？

不可以。前端结果可能被伪造，也可能因为页面关闭而丢失。我们应以通过验签和业务核对的服务端通知为主，并使用官方查询能力补偿异常状态。

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

当权益稳定、成本可预测时，我们优先考虑订阅。当成本与模型调用或资源消耗紧密相关，并且已经具备可信计量链路时，再考虑按量付费。我们也可以使用基础订阅加额度包，但必须避免同一次用量被重复计费。

问题：什么情况下不建议直接使用按量付费？

当用量无法审计、成本波动无法解释，或用户无法预估账单时，我们不建议直接使用按量付费。可以先采用固定套餐、预付额度，或设置明确的消费确认流程。

[5] 相关阅读

备注：内容仅供参考。