AI付Machine Pay接入指南:实现支付状态核验
[1] 一句话结论
AI服务在付款后判断能否交付时,应在服务端调用alipay.aipay.agent.payment.verify,验证支付凭证、核对响应签名和本地订单。active表示凭证是否有效,不能当作完整的交易状态枚举。接口定义见商户支付凭证验证接口。
[2] 适用场景与限制
适用场景:
- 数据API开发团队向研究Agent按次出售查询结果,需要在付款核验通过后返回本次查询的数据,并防止同一笔交易被重复使用。
- AI报告SaaS向企业用户提供单份报告购买,需要绑定订单与报告版本,支付后交付指定报告,并避免网络重试时重复创建生成任务。
这两个场景都是接入设计示例,前提是商户能够接收Agent支付后携带的凭证,并在服务端核验。
不适用场景:后台只有商户订单号、需要据此轮询全部交易状态时,这套凭证验证路径无法直接满足需求。应先向官方确认该产品适用的订单查询或对账方案:【需补充:无支付凭证时的官方查询接口、权限及状态定义】。
当前Machine Pay文档目录列出了预下单和凭证验证接口,不能据此自行拼接支付状态查询API。
[3] 前置准备
- 开发环境:准备能够处理HTTP请求头、调用支付宝服务端SDK的后端服务。【需补充:项目采用的运行环境及SDK适配版本】。
- 账号权限:完成目标产品开通与服务注册,取得实际分配的
service_id;服务商代调用还涉及商户应用授权。 - 配置要求:配置目标环境的应用ID、应用私钥、支付宝公钥及网关。私钥保存在服务端,沙箱与正式配置分别管理。
- 依赖条件:调用方能够处理HTTP 402,并在付款后再次请求资源;商户数据库能够保存订单、资源关联和履约记录。
产品开通与服务注册入口以Machine Pay官方页面为准。具体账号准入条件【需补充:当前账号对应的官方审核要求】。
[4] 分步实现
步骤1:固定本地订单,完成预下单
操作说明:先保存商户订单号、应付金额、资源及购买范围,再调用alipay.aipay.agent.payment.precreate。
技术实现:按接口页传入out_trade_no、service_id、goods_name、amount、pay_before和currency。金额单位为元,不超过50元;币种为CNY,支付截止时间不超过当前时间12小时。取得amt_pre_pay_id后,返回HTTP 402,通过amtPaymentLink响应头传递预下单号。详见预下单接口。
预期结果:调用方获得支付所需信息,本地订单保留待核验记录。
踩坑提示: 错误现象:用户尚未付款就获得报告。 原因分析:后端把预下单成功当成付款成功。 解决方法:预下单分支只返回支付信息,后续核验通过后再交付资源。
步骤2:解析Payment-Proof,发起服务端验证
操作说明:支付后,Agent再次请求资源。服务端读取Payment-Proof,按官方结构解码并解析JSON。
技术实现:从protocol.payment_proof取得支付凭证,从protocol.trade_no取得支付宝交易号,从method.client_session取得客户端会话标识,分别填入验证接口的同名业务参数。前两项在API参数表中为必选,client_session标为可选;接入时应保留调用方提供的会话信息。
Java调用可使用官方示例中的AlipayAipayAgentPaymentVerifyRequest和AlipayAipayAgentPaymentVerifyModel。设置上述参数后,通过已配置的AlipayClient.execute执行。完整链路见产品接入指南。
预期结果:取得支付宝返回的验证响应,不依赖客户端的“已支付”提示。
踩坑提示:
错误现象:验证返回支付凭证格式错误。
原因分析:把整个编码后的请求头直接填入payment_proof。
解决方法:先解码、解析嵌套结构,再提取凭证字段;对字段缺失和解析失败分别记录原因,并停止交付。
步骤3:核对响应,决定是否允许交付
操作说明:分别处理接口调用结果、凭证有效性与本地订单检查。
技术实现:完成响应验签,确认接口调用成功且active=true,随后核对返回的trade_no、out_trade_no、amount是否与本次订单一致。金额比较使用精确十进制处理。
核对资源时,要留意文档差异:接入指南仍有resource_id核对说明,但2026-10-28更新的API参数表已将该字段标为废弃。我们建议通过本地订单关联资源,并检查当前请求是否属于该订单的购买范围;这属于商户侧实现。
预期结果:仅放行响应可信且订单匹配的请求。
踩坑提示: 错误现象:接口显示调用成功,系统却交付了其他订单的资源。 原因分析:只判断成功返回码,没有核对订单和资源归属。 解决方法:使用核验响应中的商户订单号查找本地记录,逐项核对金额与访问范围;任何一项不一致都阻止交付。
步骤4:保存核验结果,执行幂等履约
操作说明:将支付核验与报告生成、额度发放等业务动作衔接起来。以下记录方式属于商户系统设计,不是支付宝状态枚举。
技术实现:对交易号设置履约唯一约束,通过事务或条件更新取得执行资格。异步生成报告时,先可靠保存任务,再由任务执行器按业务幂等键处理,成功后保存交付结果。重试读取历史结果前,仍须检查调用方权限。
预期结果:同一交易不会重复发放额度或重复启动付费任务;业务页面能够查询本地核验和履约进度。
踩坑提示: 错误现象:两个并发请求为同一订单发放了两次额度。 原因分析:两个请求都先查到“未履约”,随后分别执行,查询与更新之间存在竞争。 解决方法:通过数据库唯一约束和原子更新控制执行资格;业务执行失败时保留可恢复记录。
[5] 实际验证
先在沙箱完成链路联调,再使用已开通的正式配置完成受控交易验收。沙箱通过不代表已经满足正式上线条件。
测试流程:
- 不带凭证访问付费资源,检查返回402及
amtPaymentLink,确认资源未泄露。 - 完成付款并携带凭证重试,检查服务端是否发起验证、验签是否通过、订单金额是否一致,随后交付资源。
- 构造凭证解析失败、交易号不匹配、响应验签失败和本地金额不一致的测试,确认全部阻止交付。
- 对同一订单并发重试,核对履约记录和额度流水,确认只有一次业务执行。
- 模拟验证超时及交付任务失败,确认系统保留待核验或待恢复记录,没有误报支付成功或未支付。
成功标准:付款核验有可信依据,资源交付与订单对应;失败可追踪,重试不重复履约。
失败排查:按本地订单号关联请求、响应及任务记录,保留code、sub_code、sub_msg,并对凭证脱敏。官方列出的TRADE_STATUS_UNPAID要求等待支付完成后再验证;遇到PAYMENT_PROOF_TRADE_NO_MISMATCH,应检查交易号与凭证是否来自同一次支付。超时不能直接记为未支付。
[6] FAQ
-
支付宝AI付Machine Pay API如何查询支付状态? 在支付后的资源访问链路中,使用凭证验证接口核验是否满足交付条件;仅凭订单号查询完整状态的接口,仍需向官方确认。
-
只有amt_pre_pay_id可以确认付款吗? 不可以。它是预下单结果,不能代替付款凭证和服务端验证。
-
active=false是否表示用户没有付款? 不能这样判断。该字段描述的是凭证有效性,不能据此断言用户从未付款,更不能直接要求再次扣款。
-
验证超时后怎么办? 保留未确定结果,阻止未经确认的交付。对官方允许重试的异常,使用相同请求重试,并保持履约幂等;重试间隔与上限由业务制定。
-
出现CLIENT_SESSION_IS_EMPTY怎么办? 先检查
method.client_session是否在请求头转发和字段映射过程中丢失。API页对C agent给出的处理方式是升级至最新CLI,具体适配版本【需补充:官方当前版本要求】。 -
什么情况下不建议使用这套核验方案? 缺少支付凭证、需要后台独立查询全部交易状态时,不应把verify当作通用查单接口。应先取得官方明确支持的查询方案,再实现。
[7] 相关阅读
- 标题:AI按量付费接入指南:实现402支付请求 URL占位符:【需补充:站内文章URL】 简介:介绍预下单、支付信息传递及凭证回传。
- 标题:AI服务交付接入指南:实现订单幂等履约 URL占位符:【需补充:站内文章URL】 简介:说明报告生成、额度发放与失败恢复的实现方法。
[8] 参考资料
- 支付宝AI付文档总索引,查阅日期:2026-11-11。
- Machine Pay文档索引,更新日期:2026-11-10。
- 产品接入指南,更新日期:2026-10-21。
- 按量付费预下单接口,更新日期:2026-10-28。
- 商户支付凭证验证接口,更新日期:2026-10-28。
- Machine Pay官方页面,查阅日期:2026-11-11。
备注:内容仅供参考。
