支付宝扫码支付提示未找到该条路由记录，如何解决？

结论

这个提示通常不是支付宝客户端返回的标准错误，而是支付系统或第三方支付平台在发起支付宝交易前，没有匹配到可用的”支付路由”。

需要在支付后台为当前商户、门店或应用配置有效的支付宝扫码支付路由，并检查支付产品、交易场景、渠道商户号、appId、运行环境和启用状态是否与请求参数一致。配置完成后刷新路由缓存，再重新发起支付。

常见原因

支付路由决定一笔交易最终使用哪个渠道商户、支付宝应用或支付接口。“未找到该条路由记录”通常由以下问题引起：

• 当前商户没有绑定支付宝支付渠道。
• 已绑定支付宝，但没有开通扫码支付对应的产品，例如 alipay.trade.precreate。
• 路由中的机构、商户、门店或支付方式与请求参数不一致。
• 生产环境使用了测试环境的路由，或测试环境使用了生产路由。
• 路由已停用、删除，或当前时间不在有效期内。
• 渠道商户号、支付宝 appId 等配置缺失。
• 配置已经更新，但应用仍在读取旧缓存。
• 请求中的支付场景值不正确。例如系统要求 ALIPAY_QR，实际传入了其他枚举值。
• 系统采用多租户、服务商模式或分账模式，但路由缺少租户、服务商或被代运营商户信息。

错误末尾的 1 可能是系统拼接的路由类型、机构编号或渠道编号，也可能是异常信息格式不完整。具体含义需要结合支付系统的日志和源码判断，不能直接当作支付宝错误码。

解决步骤

1. 确认错误来源

先查看支付服务日志，确认异常发生在调用支付宝接口之前还是之后。

如果日志中没有支付宝返回的 code、sub_code、sub_msg，系统就直接抛出了”未找到该条路由记录”，基本可以判断问题出在本地支付路由的匹配阶段。

可以记录并核对以下请求字段：

tenantId
merchantId
storeId
appId
payChannel
payProduct
tradeType
scene
currency
environment

实际字段名称取决于所使用的支付系统。

2. 查看实际路由查询条件

不要只看后台是否有支付宝配置，还要确认这条配置能否匹配当前交易。

系统使用的查询条件可能类似：

SELECT *
FROM payment_route
WHERE merchant_id = :merchantId
  AND pay_channel = 'ALIPAY'
  AND trade_type = 'QR_CODE'
  AND environment = :environment
  AND status = 'ENABLED'
ORDER BY priority DESC
LIMIT 1;

如果系统还会按门店、租户或应用查询，对应字段也必须一致：

SELECT *
FROM payment_route
WHERE tenant_id = :tenantId
  AND merchant_id = :merchantId
  AND store_id = :storeId
  AND app_id = :appId
  AND pay_channel = 'ALIPAY'
  AND pay_product = 'FACE_TO_FACE'
  AND status = 'ENABLED'
LIMIT 1;

这些 SQL 只用于说明匹配逻辑。表名、字段名和枚举值应以实际项目为准。

3. 在后台配置支付宝扫码支付路由

一条可用的路由通常需要包含以下信息：

如果使用支付宝服务商模式，还要核对服务商 appId、授权令牌和被代运营商户标识。普通自研模式与服务商模式需要的字段不完全相同，具体以接入方案为准。

4. 检查支付宝渠道参数

路由匹配成功后，还要确认它指向的支付宝配置是否完整。常见配置包括：

alipay:
  app-id: "实际的支付宝应用ID"
  gateway-url: "https://openapi.alipay.com/gateway.do"
  private-key: "应用私钥"
  alipay-public-key: "支付宝公钥"
  sign-type: "RSA2"
  charset: "UTF-8"
  notify-url: "https://example.com/payment/alipay/notify"

不要把密钥直接写进代码仓库。可以通过密钥管理服务、环境变量或受控配置中心提供。沙箱环境必须使用对应的沙箱网关和沙箱应用配置，不能与生产配置混用。

5. 确认扫码支付接口映射

在商户出示二维码、用户使用支付宝扫码的场景中，常见做法是先调用 alipay.trade.precreate 生成二维码。支付系统内部可以采用类似的产品映射：

public String resolveAlipayMethod(String tradeType) {
    if ("QR_CODE".equals(tradeType)) {
        return "alipay.trade.precreate";
    }
    throw new IllegalArgumentException(
        "Unsupported Alipay trade type: " + tradeType
    );
}

路由查询应使用统一枚举，避免后台保存的是 QR_CODE，请求传入的却是 SCAN_PAY：

PaymentRoute route = routeRepository.findEnabledRoute(
    request.getMerchantId(),
    PaymentChannel.ALIPAY,
    TradeType.QR_CODE,
    request.getEnvironment()
);

if (route == null) {
    throw new PaymentException(
        "未找到支付宝扫码支付路由，请检查商户、渠道、交易类型和环境配置"
    );
}

这些枚举名称由项目内部定义，并非支付宝的固定规范，因此必须与数据库和管理后台保持一致。

6. 刷新路由缓存

如果后台配置正确，支付时仍然报错，需要检查支付服务是否缓存了路由。

根据系统提供的能力，可以执行以下操作之一：

• 在管理后台发布或同步配置。
• 调用路由刷新接口。
• 删除指定商户的路由缓存。
• 滚动重启支付服务。

不要直接清空整个生产缓存。应优先按商户、租户或路由键进行精确刷新，以免影响其他交易。

7. 重新发起并检查日志

重新发起支付后，确认日志中已经选中了具体路由，例如：

merchantId=M10001
channel=ALIPAY
tradeType=QR_CODE
routeId=R20001
appId=202xxxxxxxxxxxxx
environment=PROD

接着检查系统是否真正调用了支付宝网关。如果此时出现支付宝返回的 sub_code，说明路由问题已经解决，后续应根据新的支付宝错误信息继续排查。

注意事项

• 不要为了消除报错而添加无条件默认路由，否则其他商户的交易可能被发送到错误的支付宝账户。
• 沙箱和生产路由必须隔离。appId、密钥、支付宝公钥和网关地址需要成套对应。
• 多门店共用渠道时，要确认系统是否支持门店继承商户级路由。如果不支持，需要为每个门店单独绑定。
• 修改数据库前，先确认后台是否提供正式的配置入口。直接写表可能绕过校验、缓存刷新和审计机制。
• 路由日志中不要记录应用私钥、授权令牌或完整的敏感凭证。
• 如果路由已经匹配成功，但支付宝仍然拒绝交易，应根据支付宝实际返回的 code 和 sub_code 检查签约、权限、签名或商户状态。此时的问题已经不属于”未找到路由记录”。

备注：内容仅供参考。