mp-java/docs/WECHAT_PAY_CERTIFICATE_FIX.md

微信支付证书问题修复指南

问题描述

错误信息：创建支付订单失败：创建支付订单失败：Cannot invoke "java.security.cert.X509Certificate.getSerialNumber()" because "certificate" is null

问题原因

这个错误通常发生在使用微信支付SDK的 RSAAutoCertificateConfig 时，SDK尝试自动下载微信支付平台证书但失败，导致证书对象为null。

常见原因包括：

1. 商户平台未开启API安全功能
2. 未申请使用微信支付公钥
3. 网络连接问题
4. 商户证书序列号错误
5. APIv3密钥配置错误

解决方案

1. 商户平台配置

步骤1：开启API安全功能

1. 登录 微信商户平台
2. 进入【账户中心】->【API安全】
3. 点击【申请使用微信支付公钥】
4. 按照指引完成申请流程

步骤2：下载证书文件

1. 在API安全页面下载商户证书
2. 获取以下文件：
   • apiclient_cert.pem (商户证书)
   • apiclient_key.pem (商户私钥)
3. 记录商户证书序列号

步骤3：设置APIv3密钥

1. 在API安全页面设置APIv3密钥
2. 密钥必须是32位字符串（字母和数字组合）
3. 妥善保管密钥，不要泄露

2. 开发环境配置

证书文件放置

将证书文件放置到以下目录：

src/main/resources/dev/wechat/{tenantId}/
├── apiclient_key.pem     # 必需：商户私钥
└── apiclient_cert.pem    # 可选：商户证书（自动配置不需要）

例如，租户ID为10550的证书路径：

src/main/resources/dev/wechat/10550/
├── apiclient_key.pem
└── apiclient_cert.pem

数据库配置

在 payment 表中配置以下信息：

• mch_id: 商户号
• app_id: 应用ID
• merchant_serial_number: 商户证书序列号
• api_key: APIv3密钥（32位）

3. 生产环境配置

证书文件上传

将证书文件上传到服务器指定目录，通常是：

/www/wwwroot/file.ws/file/{相对路径}/

数据库配置

在 payment 表中配置证书文件的相对路径：

• apiclient_key: 私钥文件相对路径
• apiclient_cert: 商户证书文件相对路径

4. 代码修复

系统已经实现了自动回退机制：

1. 优先使用自动证书配置：RSAAutoCertificateConfig
2. 自动回退到手动配置：如果自动配置失败，会回退到 RSAConfig 或 RSAPublicKeyConfig
3. 详细错误诊断：提供具体的错误信息和修复建议

5. 诊断工具

使用证书诊断API

# 诊断特定租户的证书配置
GET /system/wechat-pay-diagnostic/diagnose/{tenantId}

# 获取解决方案
GET /system/wechat-pay-diagnostic/solutions

# 测试证书配置
POST /system/wechat-pay-diagnostic/test/{tenantId}

查看诊断日志

在应用日志中查看详细的诊断信息：

=== 微信支付证书诊断报告 ===
租户ID: 10550
商户号: 1723321338
应用ID: wx1234567890abcdef
商户证书序列号: 2B933F7C35014A1C363642623E4A62364B34C4EB
APIv3密钥: 已配置(32位)
证书文件路径: dev/wechat/10550/apiclient_key.pem
证书文件存在: 是
配置验证结果: 通过

常见问题排查

Q1: 404错误

原因：商户平台未开启API安全功能 解决：按照上述步骤1开启API安全功能

Q2: 证书序列号不匹配

原因：数据库中配置的序列号与实际证书不符 解决：

1. 在商户平台查看正确的序列号
2. 更新数据库中的 merchant_serial_number 字段

Q3: APIv3密钥错误

原因：密钥长度不是32位或包含非法字符 解决：

1. 重新设置32位APIv3密钥
2. 确保只包含字母和数字

Q4: 私钥文件不存在

原因：证书文件路径错误或文件未上传 解决：

1. 检查文件路径是否正确
2. 确保文件已正确放置

Q5: 网络连接问题

原因：服务器无法访问微信支付API 解决：

1. 检查网络连接
2. 确保防火墙允许HTTPS出站连接
3. 检查代理设置

最佳实践

1. 使用自动证书配置：推荐使用 RSAAutoCertificateConfig，可自动管理平台证书
2. 定期检查证书有效期：避免证书过期导致的问题
3. 妥善保管私钥：确保私钥文件安全，不要泄露
4. 使用HTTPS：所有支付相关通信都应使用HTTPS
5. 监控日志：定期查看支付相关日志，及时发现问题

技术支持

如果按照以上步骤仍无法解决问题，请：

1. 查看完整的错误日志
2. 使用诊断API获取详细信息
3. 检查微信商户平台的配置状态
4. 联系技术支持团队

相关文档

• 微信支付官方文档
• API安全配置指南
• 证书和回调报文验证