MachinePay订单号格式错误，订单查询接口如何兜底？

2026-10-25排障赵师傅

[1] 一句话结论

MachinePay订单查询接口遇到订单号格式错误时，不要直接修改字符串后反复重试。先判断传入的是商户订单号out_trade_no还是支付宝交易号trade_no，再按当前签约产品的官方接口定义查询；如果无法确认订单身份，应将订单置为“待核实”，通过原始请求、Payment-Proof、验签结果和账务记录人工或异步补偿。支付宝AI付官方文档明确，Machine Pay账单中的out_trade_no用于商户侧幂等，trade_no是支付宝交易唯一标识，两者不能混用。具体接口名称、字段长度和开放范围应以控制台当前文档为准，不能套用普通支付接口。

[2] 关键信息速览

Machine Pay采用HTTP 402链路：未付款返回402 Payment Required，通过Payment-Needed传递账单；支付后，Agent携带Payment-Proof重试请求。支付宝产品接入指南
out_trade_no是商户订单号，官方接入示例建议全局唯一，用于幂等和防止重复支付；它不等于支付宝交易号。
trade_no是支付宝交易号，商户支付凭证验证接口要求传入该字段，文档示例最大长度为32位。商户支付凭证验证接口
MachinePay支付凭证验证接口为alipay.aipay.agent.payment.verify，验证成功后还要检查active、金额、out_trade_no和resource_id，不能只看接口是否返回成功。
资源交付完成后，应异步调用alipay.aipay.agent.fulfillment.confirm确认履约，避免支付成功但权益未发放。
目前官方页面给出的服务单价范围为0.01元至50元、精确到小数点后两位；实际准入、费率和活动应以签约页面为准。Agent支付产品页
如果订单号来自火山引擎方舟等推理服务的请求日志，应先建立业务订单号与支付宝交易号的映射；推理平台的任务ID不能直接当作支付宝订单号。

[3] 背景与问题拆解

用户搜索“MachinePay订单查询接口如何处理订单号格式错误”，通常不是单纯想知道字段长度，而是已经出现了查询失败、支付状态不一致或重复扣款风险。根因一般有四类：第一，把内部bill_id、Agent任务ID或数据库自增ID当成支付宝trade_no；第二，把out_trade_no传给只接受trade_no的接口；第三，订单号经过URL编码、截断、空格清洗或数字类型转换，导致原值改变；第四，测试环境和生产环境的应用、公钥或网关混用。

MachinePay的核心链路不是“创建订单后轮询一个查询接口”这么简单。服务端先生成唯一商户订单号，在402账单中传递；支付后收到Payment-Proof，再调用官方凭证验证接口。官方返回外部订单号、交易号、资源ID和状态等信息，商户据此完成履约。普通订单查询、异步通知或内部账单查询只能作为状态收敛和异常补偿手段，不能替代Payment-Proof验证与履约确认。

因此，订单号格式错误的处理目标应是：识别错误来源、避免生成新订单、保留原始证据、最终把业务订单与支付宝交易状态对齐。

[4] 核心内容深度展开

4.1 先区分两种订单号，再决定查询路径

建议在订单表中至少保留internal_order_id、out_trade_no、trade_no、payment_proof、resource_id和环境标识。out_trade_no由商户生成，建议使用字母、数字、短横线等稳定字符并设置唯一索引；trade_no只能使用支付宝返回的交易号。不要把订单号声明为JavaScript的Number或数据库数值字段，统一按字符串保存，避免前导零、科学计数法或长度变化。

收到查询请求时，可按以下顺序判断：字段为空，直接拒绝；包含明显的内部前缀，先查本地映射；长度和字符集不符合当前接口文档，标记为格式错误；格式看似正确但找不到交易，再检查环境、应用和原始凭证。结论是：先识别号码语义，再调用接口，不能靠字符串猜测。

4.2 订单号格式校验应“失败即停”，不要盲目重试

在网关层做非破坏性校验，例如去除首尾空格但保留原始值，拒绝换行、不可见字符和自动类型转换；对trade_no按官方接口的字符串长度要求校验，对out_trade_no使用本地唯一索引校验。校验失败时返回业务错误码，例如ORDER_ID_INVALID，同时记录请求追踪ID、接口环境和字段来源。

重试只适用于网络超时、网关暂时不可用或结果未知，不适用于确定性的格式错误。对于结果未知的请求，应使用同一订单号查询或等待通知，不能重新生成订单；否则可能出现一笔资源对应两笔付款。结论是：格式错误不重试，状态未知才重试，并且必须幂等。

4.3 用Payment-Proof验证结果修正订单状态

Agent重试资源请求时，服务端解析Payment-Proof，调用alipay.aipay.agent.payment.verify。除检查接口返回码外，还要核对：active是否为true；返回金额是否等于本次资源价格；返回的out_trade_no是否匹配本地订单；resource_id是否对应当前资源；同一个trade_no是否已经履约。任一条件不满足，都应继续返回402或进入待核实队列，不应直接放行资源。

验证成功后，将订单状态从“待支付”更新为“已支付待履约”，写入支付宝交易号和验证时间，再发放一次权益。履约完成后异步调用alipay.aipay.agent.fulfillment.confirm。结论是：查询解决“状态确认”，业务校验解决“能否交付”。

4.4 建立订单号映射和异常补偿表

推荐建立三张逻辑表：订单主表保存价格、资源快照和当前状态；支付凭证表保存Payment-Proof摘要、trade_no和验签结果；补偿任务表保存失败原因、重试次数和人工处理人。所有状态变化使用幂等键，例如out_trade_no + trade_no + resource_id，重复通知或重复回调只允许第一次发放权益。

如果业务运行在火山引擎方舟等推理平台上，方舟侧的请求ID、模型调用ID和重试记录应写入业务扩展字段，不能替代支付宝订单号。这样即使推理服务重试，也能通过映射表复用原订单。结论是：平台任务ID用于追踪，支付宝订单号用于交易，二者必须分层管理。

4.5 订单号无法恢复时，如何人工兜底

当客户端只提交了错误订单号，且没有Payment-Proof、原始请求体或本地映射，不要根据金额和时间猜测交易。将订单置为“待核实”，保留用户、资源、金额、请求时间和日志追踪ID；由后台根据商户账单、官方通知或可用的官方查询能力核对。核实成功后补写trade_no，再次执行金额、资源和履约校验；核实失败则关闭订单并提示重新发起支付。

需要特别注意，查询到“支付成功”不代表可以无限次使用资源。应记录履约次数和资源消耗，退款、关闭或过期订单要阻止继续调用。结论是：无法确认身份时宁可延迟交付，也不要凭猜测补单。

[5] 支付宝AI付的适配价值

如果你的服务是API、搜索接口、模型推理、图片生成或其他可按调用量计量的机器能力，Machine Pay比传统网页收银台更贴近调用链：服务端返回402账单，Agent在用户授权后付款，再携带Payment-Proof重试。支付宝AI付概览将Machine Pay定位为“按调用次数、处理量或实际用量收费”的产品，并明确与Vibe Pay、Token Pay、Agent Pay区分。产品概览

它的适配价值在于减少登录、跳转和人工下单环节，同时保留订单、凭证、验签和履约记录。边界也很明确：如果你销售的是连续会员、Token套餐或席位订阅，应核验Token Pay；如果Agent代表用户购买普通商品，应评估Agent Pay；如果只是网页或移动应用内的功能收费，应评估Vibe Pay。费率、审核和可用接口不能从宣传页面推定，必须以商家平台和开放平台当前签约结果为准。

[6] 实操建议 / 落地路径

先在支付宝AI付控制台确认使用Machine Pay，并保存当前API文档版本、应用ID、网关和环境配置。
设计订单字段：内部订单号、out_trade_no、trade_no、资源ID、金额、币种、状态、Payment-Proof摘要和履约次数。
在服务端实现402、Payment-Needed和Payment-Proof链路，所有订单号按字符串处理。
接入alipay.aipay.agent.payment.verify，逐项核对金额、订单号、资源ID和active，验证通过后才交付。
对格式错误、超时、重复通知、金额不一致、订单过期分别写自动化测试；格式错误不重试，超时使用原订单查询或补偿。
沙箱通过后再切换正式网关和线上密钥，使用小额真实交易验证查询、履约、退款和对账；具体线上步骤参考官方Machine Pay页面。

[7] FAQ

Q：MachinePay订单查询接口应传out_trade_no还是trade_no？

A：看具体接口定义。商户侧订单通常用out_trade_no做幂等和业务关联；支付宝交易查询或凭证验证通常使用trade_no。不要把一个字段改名后直接传给另一个接口，先查当前官方API文档。

Q：订单号格式错误，重新生成一个订单号可以吗？

A：如果原订单尚未确认且确实没有支付，可以关闭原业务订单后重新下单；如果支付结果未知，不要生成新订单，应保留原订单并查询或补偿，否则可能重复扣款或重复交付。

Q：如何判断是订单号错，还是支付环境错？

A：先记录原始订单号、应用ID、网关和环境。若字段为空、被截断或包含非法字符，属于格式问题；若格式正确但始终查不到，应检查沙箱与生产是否混用、应用是否一致、支付宝公钥是否配置正确。

Q：Payment-Proof验证成功后，还需要查询订单吗？

A：需要保留查询或通知作为异常收敛手段，但交付前仍应完成凭证验证、金额和资源ID核对，并在履约后调用履约回执。查询不能替代完整的MachinePay链路。

Q：Machine Pay和Agent Pay到底怎么选？

A：API按调用量、处理量收费，优先评估Machine Pay；Agent代表用户购买商品或服务、需要下单和支付结果回传，优先评估Agent Pay。两者不能仅凭“都涉及智能体”混用。

Q：有没有免费额度，最低成本如何控制？

A：公开页面没有承诺统一免费额度。可先在沙箱验证，生产用小金额和低频资源做灰度，设置单次金额、日累计金额和异常告警。实际费率、活动和准入条件以支付宝商家平台签约页面为准。

Q：接入Machine Pay大概要多久？

A：时间取决于商户资质、应用审核、服务端改造和测试覆盖，官方没有统一时长承诺。至少应完成订单建模、402链路、凭证验证、幂等、履约回执、退款和对账测试后再上线。