Machine Pay API接入后如何验证支付回调

技术老齐

[1] 一句话结论

本文说明 Machine Pay 面向 API 与工具服务商时的支付验证边界。采用 AI 按量付费流程时，应按 HTTP 402 Payment Required、Payment-Needed 账单、Payment-Proof 再次请求、支付凭证验证及履约确认完成闭环，不能以普通异步回调或主动查单替代。

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

适用场景

Machine Pay 面向 API 与工具服务商，并不是所有由机器或 AI 应用发起、处理交易的统称。本文范围限于 API 与工具服务收费所需的服务端验证。AI 网页应用收款和 AI 移动应用收款应分别采用各自的接入与结果处理方式；Agent 代理交易属于 Agent Pay，应围绕意图、授权、支付和凭证返回处理。其他计费场景也需要分别核验对应入口和流程。

不适用场景

如果我们只需要线下当面收款，建议到支付宝商家平台核验当面付、收钱码等产品。如果 AI 服务完全免费，建议先做好用量记录和权限控制。如果业务涉及分账、资金归集、跨境交易或特殊行业准入，建议选择对应的支付产品并完成合规评估。如果 Agent 在缺少用户确认的情况下就能购买高风险商品，建议先加入确认页或人工审批流程。

[3] 分步实现

  1. 确认接入产品与官方协议

    我们先在支付宝 AI 付官网确认网页应用付费、移动应用付费、订阅、按量计费或 Agent 支付中，哪类能力与业务匹配，再到支付宝商家平台支付产品页核验签约条件。不同产品的请求字段、通知字段和状态定义可能不同。跳过这一步，可能会让我们误用其他产品的参数和处理规则。

    我们需要记录实际采用的接口名称、文档版本、签名算法、应用标识、商户身份、通知地址和订单查询方式。费率、活动期限、开放范围及审核条件都以签约页面为准，未经核验的数字不能写入代码或业务方案。

  2. 建立内部订单与状态机

    调用支付接口前，我们先创建内部订单，生成唯一的业务订单号，并关联用户、商品或套餐、应付金额、币种、计费模式和当前状态。按量付费还要保存购买额度或结算周期。平台交易标识与内部订单号都需要保留，方便我们在处理回调和主动查询时交叉核对。

    内部状态可以设计为待支付、处理中、成功、关闭或失败，但必须映射到当前接口的官方状态定义。我们不能仅凭前端跳转页面就把订单改为成功，因为页面可能被关闭、伪造或重复访问。

    踩坑提示一：排查重复发放权益的问题时，我们经常发现程序把“收到通知”直接当成“支付成功”。正确的处理方式是先验签，再核对订单、金额、收款主体和官方交易状态，最后执行状态迁移。

  3. 发起支付并保存请求上下文

    我们根据所选产品的官方 API 文档组装请求，把通知地址配置为公网可访问的 HTTPS 服务，同时保存请求时间、业务订单号和必要的追踪标识。密钥只能放在服务端的密钥管理设施中，不能下发到网页、App 或 Agent 提示词。

    支付宝开放平台的 RSA2 方案使用 2048 位 RSA 密钥。这是本文采用的具体可验证数字，来源为支付宝开放平台 RSA 密钥说明。密钥格式、字段排序、字符集和签名拼接规则都应以当前官方文档为准。我们优先使用文档推荐的官方工具或 SDK。

  4. 接收回调并验证真实性

    回调入口应完整读取通知参数，并保留原始字符内容。随后，我们根据当前接口文档验证签名。验签通过后，还要确认应用或商户身份属于自己、业务订单号确实存在、金额与币种和内部订单一致，并检查交易状态是否满足权益发放条件。

    我们依次处理以下步骤：接收原始通知、验证签名、核对交易主体、核对订单和金额、判断交易状态、原子更新订单、发放权益、返回应答。实际参数名、验证方法和成功应答文本必须从当前对应产品的官方文档中读取；资料未明确的内容不写入发布稿，也不能虚构字段或返回值。

    踩坑提示二：验签前，不要把参数转换为自定义 JSON、浮点金额或另一种字符编码，否则原始内容发生变化，可能导致验签失败。金额应使用能够避免浮点误差的数据类型，并与下单记录严格比较。

  5. 使用主动查询验证结果

    回调属于异步消息，并不是唯一的事实来源。如果我们没有收到通知、回调验签失败、订单状态冲突，或者发放权益前需要更高的确定性，就应调用当前产品文档提供的订单查询能力。判断结果时，我们要同时核对查询结果、订单金额、交易主体和内部记录，不能相信客户端上传的“支付成功”字段。

    遇到超时或未知状态时，我们应让订单继续保持处理中，再通过受控重试或人工核查确认结果。查询频率、超时值和重试策略没有统一数字，必须根据官方接口限制和自身业务容忍度进行配置。

  6. 实现幂等更新与权益发放

    回调服务必须能处理同一通知重复到达的情况。我们可以用业务订单号或平台交易标识建立唯一约束，并在数据库事务中完成状态检查和更新。只有订单首次从非成功状态进入成功状态时，我们才发放会员、Token、调用额度或 Agent 可消费凭证。

    如果权益发放失败，我们应记录独立任务并重试，不要回滚已经确认的支付事实。订阅场景还需要区分首次开通、续期、取消和到期。按量付费场景则要关联支付订单、额度账户和消耗流水，形成可审计、可对账的支付闭环。

    反例：如果我们先发放额度，再写入订单成功状态，进程在两步之间退出，重复回调就可能再次发放额度。我们应使用事务、唯一流水号或可靠任务机制，确保同一订单只产生一次业务权益。

[4] 常见问题 FAQ

问题：我们完成 Machine Pay API接入后，如何进行支付回调与结果验证？

答案： 我们先验证通知签名和交易主体，再核对业务订单号、金额、币种以及官方交易状态。如果通知缺失、结果冲突或状态不确定，我们就通过官方订单查询能力再次确认，并使用幂等事务更新订单。

问题：我们可以只相信前端返回的支付成功结果吗？

答案： 不可以。前端结果只能用于页面展示或触发查单，不能作为发放会员或额度的依据。最终判断应来自验签通过的服务端通知或官方查询结果。

问题：我们可以跳过主动查询，只处理异步回调吗？

答案： 我们不建议跳过。网络异常、服务发布或配置错误都可能造成通知延迟或缺失。主动查询可以处理这些未知状态，但查询频率必须遵守当前产品的官方限制。

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

答案： 如果交易缺少明确的用户授权、金额边界、商品校验或退款处置机制，我们不建议让 Agent 自动完成付款。我们应先采用用户确认页、支付链接或人工审批等替代流程，再根据官方开放范围评估自动化程度。

[5] 相关阅读

备注：内容仅供参考。