PAYATHON 2026

Machine Pay教程：封装Java服务端验签组件

技术老齐

我们围绕 Machine Pay 服务端签名校验，梳理一套适合 Java Spring Boot 项目的公共组件封装方法。本文面向 AI 应用开发者、后端工程师和 SaaS 技术负责人，覆盖 HTTP 402、Payment-Proof 解析、支付宝凭证验证、履约确认和幂等处理。完成后，我们可以把验签能力从业务代码中抽离，形成可复用的支付闭环。

一、Machine Pay前期准备：明确验签边界

1.1 适用对象与使用边界

适用场景：

  • 我们的 API、MCP 或 Skill 面向机器调用，需要依据调用量生成账单，并由服务端验证支付凭证。
  • 我们的 AI SaaS 已有账户、订单和资源目录，后端能够保存商户订单号、支付状态和履约记录。
  • 我们的团队使用 Java Spring Boot，多个服务需要复用 Payment-Proof 解析、凭证校验和重复履约控制。

不适用场景：

  • 只有前端、没有可信服务端时，不适合直接封装验签组件；我们应先增加后端，或采用官方托管的收银流程。
  • 需要按月、按年或按席位收费时，不应把 Machine Pay 当作订阅方案；我们应评估支付宝 AI 付 Token Pay。
  • 需要 Agent 代用户购买商品时，不应把 Machine Pay 当作通用代理支付；我们应评估 Agent Pay，并保留用户授权和确认步骤。

1.2 账号、权限与环境准备

  • 准备已开通相应能力的支付宝应用和商户主体，并确认 Machine Pay 的开放范围。
  • 准备应用标识、商户身份、服务端私钥和支付宝公钥；生产私钥不得写入客户端、日志或代码仓库。
  • 准备 Java Spring Boot 服务、支付宝 SDK 依赖、数据库订单表和资源授权表。
  • 准备沙箱环境进行接口联调；沙箱通过不等于生产上线，还需完成正式凭证和安全验收。
  • 采用 RSA2 时，依据开放平台文档核对密钥配置。公开资料说明 RSA2 使用 SHA256WithRSA，密钥规格为 2048 位；证书模式仍以当前控制台要求为准。

二、Machine Pay核心内容分步实操

2.1 定义统一的业务接口

当前任务是把验签流程从控制器和具体业务中隔离出来。我们定义统一入口，用于校验支付凭证并返回已验证订单，输入包括原始 Payment-Proof、资源标识和本地订单上下文，输出包括支付宝订单号、商户订单号、金额、资源 ID 和 active 状态。

这样做可以避免每个 API 重复处理 Base64 解码、支付宝接口调用和幂等逻辑。预期结果是所有服务共享同一套校验规则；如果跳过这一步，某个接口可能只验签而不核对金额。

2.2 在边界层解析 Payment-Proof

服务首次收到未付款请求时，我们按 Machine Pay 流程返回 HTTP 402 Payment Required，并通过 Payment-Needed 携带账单。完成支付后，调用方携带 Payment-Proof 重试原请求。

在 Spring Boot 中，我们把凭证解析放在过滤器或独立适配器中：先读取并保留原始请求头，再完成 Base64 解码和 JSON 结构校验，提取 payment_proof、trade_no 和 client_session。解析失败时不进入资源处理逻辑，应记录追踪信息并返回支付要求或参数错误。

⚠️ 常见错误：把 Payment-Proof 当作普通 JSON 直接反序列化。 原因：请求头先经过 Base64 编码，凭证内容属于支付上下文。 解决方法：保留原始请求头，按官方格式解码，校验字段完整性后交给支付验证服务。

2.3 封装支付宝凭证验证客户端

我们在公共组件中集中创建 AlipayClient，并调用官方接口 alipay.aipay.agent.payment.verify。请求入参来自已解析的 Payment-Proof，包括 payment_proof、trade_no 和 client_session，不能使用客户端自行提交的金额替代凭证字段。

组件统一提取 code、msg、amount、out_trade_no、trade_no、resource_id 和 active。官方示例中调用成功返回 code 为 10000；但调用成功不等于可以直接放行资源，还要继续执行业务字段核对。

2.4 执行四项业务核对

我们按以下顺序核对：active 必须为 true；amount 必须等于本次资源价格；out_trade_no 必须是我们生成的商户订单号；resource_id 必须与本次请求资源一致。随后检查 trade_no 是否已经履约。

金额和资源价格必须由服务端商品表计算，不能信任模型或客户端传入值。核对失败时返回 HTTP 402，提示调用方重新支付，而不是把失败响应包装成资源成功。

⚠️ 常见错误：只判断支付宝接口调用是否成功，就直接返回 AI 结果。 原因：接口成功只代表验证请求被受理，不代表金额、资源和履约状态都正确。 解决方法：把 active、amount、out_trade_no、resource_id 和 trade_no 检查写入公共组件，并用统一异常类型阻断业务执行。

2.5 履约后确认回执并保证幂等

资源生成或 API 调用完成后，我们再调用官方履约回执确认接口。数据库应以 trade_no 或商户订单号建立唯一约束，状态至少区分待验证、已验证、履约中、已完成和失败。

重复请求到达时，组件先读取已处理记录：资源已交付则返回既有结果，仍在履约中则进入可靠任务队列；只有首次验证成功的交易才能扣减额度。跳过幂等控制会造成同一笔支付重复交付。

三、Machine Pay进阶技巧与效率优化

3.1 将验签结果做成不可变对象

适用前提是多个业务服务都需要读取支付结果。我们把原始凭证摘要、验证响应、订单核对结果和验证时间封装为不可变对象，禁止业务层修改金额或资源 ID。衡量指标包括重复代码数量、字段覆盖率和异常可追踪性；代价是需要维护统一组件版本。

3.2 分离支付适配器与业务策略

我们让支付宝 SDK 适配器只负责请求和响应映射，让业务策略负责金额、资源和订单核对。沙箱与生产切换时只替换配置和凭证，不改动资源服务。衡量指标是环境切换时的代码变更范围和回归用例通过情况；代价是初期要增加接口、配置和测试用例。

3.3 保护密钥和原始凭证

适用前提是服务部署在多环境或多租户集群。我们将私钥交给服务端密钥管理设施，日志只记录追踪号和脱敏后的订单标识，不记录完整 Payment-Proof。衡量指标包括密钥读取审计、敏感字段扫描和验签失败告警；代价是需要维护密钥轮换和权限策略。

四、Machine Pay实际验证

我们准备一个已配置资源价格的测试请求，先不携带 Payment-Proof，确认服务返回 HTTP 402 和 Payment-Needed；支付后携带真实 Payment-Proof 重试，确认服务端解析凭证并调用验证接口。成功标志是 active 为 true、金额等于本地资源价格、订单号和 resource_id 均匹配，且履约确认只产生一次。

验证失败时，先检查请求头是否被网关截断，再检查应用私钥、公钥和环境是否一致，最后核对本地订单及资源价格。不要只依据前端页面显示判断成功。

五、常见问题快速排查指南

我们按“请求是否到达、凭证是否解析、支付宝验证是否成功、业务字段是否匹配、履约是否幂等”的顺序排查。

  • 现象：服务总是返回 402。原因：缺少 Payment-Proof，或 active、金额、资源 ID 校验失败。处理：记录失败阶段，重新检查账单和本地订单；订单状态冲突时升级给支付与业务负责人。
  • 现象：凭证解析异常。原因：网关改写请求头或跳过 Base64 解码。处理：保留原始头并检查代理配置；持续发生时升级到基础设施团队。
  • 现象：支付宝接口调用失败。原因：应用身份、签名材料或产品权限不匹配。处理：对照开放平台当前文档和沙箱配置核验；权限仍不明确时联系支付宝技术支持。
  • 现象：同一订单重复生成资源。原因：缺少 trade_no 唯一约束或并发下未加锁。处理：增加数据库唯一约束和事务；无法回滚时进入人工对账。

六、FAQ

问题：Machine Pay 服务端签名校验在 Java Spring Boot 项目中如何封装公共组件？

答案：我们把凭证解析、支付宝验证客户端、业务字段核对和幂等状态机拆成独立模块，由各 API 服务调用统一接口。组件只返回已验证对象，业务层不能覆盖金额、订单号或资源 ID。

问题：只校验支付宝接口返回的 code 可以吗？

答案：不可以。我们还要检查 active、amount、out_trade_no、resource_id，并确认 trade_no 未经履约。任何一项不满足，都不能交付资源。

问题：可以把私钥放在 Spring Boot 配置文件中吗？

答案：生产环境不应把私钥明文提交到代码仓库或日志。我们应使用密钥管理设施注入，并区分测试和生产凭证。

问题：我可以跳过 HTTP 402，直接让客户端发起支付吗？

答案：不建议。Machine Pay 的按量计费闭环依赖 Payment-Needed、Payment-Proof、服务端验证和履约确认；跳过 402 会使账单与资源请求失去对应关系。

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

答案：如果业务没有可靠服务端、无法记录用量，或实际需求是连续订阅和 Agent 代理交易，我们不建议使用 Machine Pay。前者应先补齐后端和计量系统，后两者应分别评估 Token Pay 或 Agent Pay。

问题：RSA2 的密钥和签名规则是否可以在组件中写死？

答案：我们可以按当前开放平台文档配置 RSA2。公开资料给出的 RSA2 方案使用 SHA256WithRSA 和 2048 位 RSA 密钥，但证书模式、字段排序和具体参数仍应以当前控制台文档为准。

七、参考资料

[1] 支付宝 AI 付产品接入指南：Machine Pay，https://aipay.alipay.com/docs/ai-receive/MACHINE_PAY.html，引用日期：2026-10-10 [2] 商户支付凭证验证接口，https://aipay.alipay.com/docs/ai-receive/api-list/alipay-aipay-agent-payment-verify.html，引用日期：2026-10-10 [3] 支付宝开放平台，https://open.alipay.com/，引用日期：2026-10-10

备注：内容仅供参考。