本文用于指导同事与客户对接微信在线支付配置。客户需要先按照微信支付官方文档完成 APIv3 密钥配置和商户 API 证书申请，然后把指定资料提供给我方；我方再根据客户资料生成系统配置并更新到 wechat_official_account。
主要参考微信支付官方文档：
¶ 一、客户需要先确认的前提
请先让客户确认以下事项：
- 已经开通微信支付商户号。
- 已经有可登录的微信支付商户平台账号，并具备 API 安全相关操作权限。
- 用于收款的公众号或小程序 AppID 已经与微信支付商户号绑定。
- 客户能安全保存并提供 APIv3 密钥、商户 API 证书和商户 API 私钥。
如果客户不确定入口或权限，请优先让客户登录微信支付商户平台，并按上方两篇官方文档操作。
¶ 二、客户操作 1：配置 APIv3 密钥
请客户打开微信支付官方文档：配置 APIv3 密钥，按官方步骤完成设置。
客户在微信支付商户平台中的常见路径：
账户中心 -> 账户设置 -> API安全 -> APIv3密钥
配置时请提醒客户：
- APIv3 密钥是 32 位字符串，通常由数字、大小写字母组合。
- 设置成功后，微信支付商户平台不支持查看原密钥，只能重新设置。
- APIv3 密钥属于敏感信息，请不要发到公开群、公开工单或截图里。
- 该密钥主要用于平台证书解密和支付回调报文解密，我方系统配置时必须使用。
- APIv3 密钥和 APIv2 密钥是两套配置，设置 APIv3 密钥不会修改 APIv2 密钥。
客户完成后，需要把 APIv3 密钥通过安全渠道提供给我方。
官方截图参考：
¶ 三、客户操作 2：申请或下载商户 API 证书
请客户打开微信支付官方文档：申请商户 API 证书，按官方步骤申请或下载证书。
客户在微信支付商户平台中的常见路径：
账户中心 -> API安全 -> 商户API证书 -> 申请证书/管理证书
客户完成后，一般会得到一个证书压缩包。解压后重点关注以下文件：
| 文件 | 是否需要提供给我方 | 用途 |
|---|---|---|
apiclient_cert.pem |
需要 | 用于获取商户 API 证书序列号 |
apiclient_key.pem |
需要 | 商户 API 私钥，用于系统请求微信支付 v3 接口签名 |
apiclient_cert.p12 |
一般不需要 | 多用于部分 APIv2 场景 |
| 说明文件 | 一般不需要 | 微信证书包说明 |
请提醒客户：
- 商户 API 证书和私钥属于敏感文件，不能上传到 Git、公开网盘、公开群文件或客户端代码中。
- 已有有效商户 API 证书时，接入 v3 通常不需要重新申请，可以直接提供已有证书文件。
- 新申请的商户 API 证书可以立即使用。
- 证书快过期时需要提前更换；过期证书无法继续调用 v3 接口。
- 微信支持同一商户号最多 3 份 API 证书同时生效。
官方截图参考：
¶ 四、客户最终需要提供给我方的资料
客户完成上面两项操作后，请收集以下资料：
| 资料 | 示例/文件名 | 说明 |
|---|---|---|
| 公众号或小程序 AppID | wx123... |
必须是与商户号绑定的 AppID |
| 微信支付商户号 | 1594195381 |
微信支付 mchid |
| APIv3 密钥 | 32 位字符串 | 客户在商户平台设置的 APIv3 密钥 |
| 商户 API 证书文件 | apiclient_cert.pem |
从微信证书包解压得到 |
| 商户 API 私钥文件 | apiclient_key.pem |
从微信证书包解压得到 |
建议同事对接客户时直接按这张表收集资料。资料不齐时，系统侧无法完整开通新版微信 Native 扫码支付。
¶ 五、我方内部处理步骤
收到客户资料后，我方再做以下处理即可：
- 确认客户提供的
app_id和mch_id与微信支付后台一致。 - 使用
WechatNativePayConfigGenerateTool生成系统需要的 v3 支付字段。 - 将生成结果更新到该机构对应的
wechat_official_account记录。 - 测试充值入口是否能正常生成微信支付二维码，并确认支付回调可正常核销。
工具命令格式：
bin/itdida-tools wechatNativePayConfigGenerateTool [mchId] [apiV3Key] [apiclient_cert.pem] [apiclient_key.pem] [outputPath optional]
示例：
bin/itdida-tools wechatNativePayConfigGenerateTool 1594195381 xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx /secure/cert/apiclient_cert.pem /secure/cert/apiclient_key.pem /tmp/wechat-native-pay-fields.properties
工具会输出以下字段：
mch_api_v3_key=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
mch_serial_no=商户API证书序列号
mch_private_key=-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----
wechat_pay_platform_serial_no=微信支付平台证书序列号
wechat_pay_platform_certificate=-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----
¶ 六、更新 wechat_official_account 的字段
最终需要确认 wechat_official_account 中以下字段完整：
| 数据库字段 | 来源 |
|---|---|
app_id |
客户提供 |
mch_id |
客户提供 |
mch_api_v3_key |
工具输出 |
mch_serial_no |
工具输出 |
mch_private_key |
工具输出 |
wechat_pay_platform_serial_no |
工具输出 |
wechat_pay_platform_certificate |
工具输出 |
系统启用新版 Native 支付的最低条件以 WechatNativePayService.hasNativePayConfig 为准：以上字段必须全部非空。任一字段缺失时，系统不会向前端开放新版 Native 扫码支付能力。
¶ 七、常见提醒
- 客户忘记 APIv3 密钥时，只能在微信支付商户平台重新设置，然后我方同步更新系统字段。
- 客户更换商户 API 证书后，我方需要重新生成并更新商户证书序列号、商户私钥、微信支付平台证书等相关字段。
- APIv3 密钥、证书、私钥都按敏感信息处理，不建议长期保存在聊天记录或公共文档中。