微信支付 APIv3 操作图文教程

本文说明如何在微信支付商户平台完成 APIv3 所需材料的申请与配置,适合对接易览云及相关业务系统的支付功能。全程建议由商户号超级管理员操作。


正式操作前请准备:

1)已开通的微信支付商户号(已绑定业务所用公众号 / 小程序 AppID)
2)超级管理员手机(收短信验证码)与操作密码
3)一台 Windows / Mac 电脑(用于下载「证书工具」生成证书)
4)自行拟定一串 32 位 APIv3 密钥(数字 + 大小写字母),设置后平台不可再查看,请先记好


一、登录商户平台,进入 API 安全

打开 https://pay.weixin.qq.com/ 登录商户平台,进入:
账户中心 → 账户设置 → API安全
在此页面完成:设置 APIv3 密钥、申请商户 API 证书、查看证书序列号。

API安全总览


二、设置 APIv3 密钥

1)在「APIv3密钥」一行点击设置(已设置过则点修改)
2)确认已与技术人员沟通后,输入 恰好 32 个字符 的密钥
3)输入操作密码 + 短信验证码完成验证
4)设置成功后请立即把密钥交给技术人员或填入业务后台;平台之后只能「重新设置」,不能回看原文

说明:APIv3 密钥与 APIv2(MD5)密钥相互独立,改 v3 不会影响 v2。

设置APIv3密钥


三、申请商户 API 证书

APIv3 调用接口签名必须使用商户 API 证书私钥。若以前做过 v2 证书,一般可继续使用同一套证书,只需再取序列号即可;没有证书请按下面步骤新申请:

1)在「商户API证书」点击申请证书,下载并安装官方证书工具(WXCertUtil)
2)打开工具,填入商户号、商户名称 → 下一步
3)工具生成「证书请求串」→ 复制粘贴到商户平台 → 安全验证
4)商户平台生成「证书串」→ 粘贴回证书工具 → 生成成功
5)点击「查看证书文件夹」,把生成的文件交给技术人员妥善保管

证书工具申请流程


四、证书文件说明(重点保管私钥)

证书目录中通常包含:

apiclient_key.pem —— 商户私钥(APIv3 签名必用,丢失无法找回,只能作废重申)
apiclient_cert.pem —— 商户证书
apiclient_cert.p12 —— PKCS12 证书包
请勿把私钥上传到公开仓库或发给无关人员。

证书文件说明


五、获取证书序列号

回到商户平台:API安全 → 商户API证书 → 管理证书,复制页面上的证书序列号(一长串十六进制字符)。

也可用命令查看:

openssl x509 -in apiclient_cert.pem -noout -serial

查看证书序列号


六、填写到业务系统后台

将材料部署到服务器后,在系统后台「微信支付」配置中选择 API v3,依次填写:

· 商户号 mch_id
· APIv3 密钥
· 证书序列号
· 私钥路径(服务器上 apiclient_key.pem 的绝对路径,例如 /www/wwwroot/你的站点/runtime/cert/apiclient_key.pem)
· 证书路径(apiclient_cert.pem,按系统要求选填)

保存后建议用 0.01 元做一笔真实支付 / 退款联调,确认回调能正常解密验签。

后台填写APIv3配置


七、产品中心还需开通的能力

按实际场景在商户平台「产品中心」开通并配置:

· JSAPI 支付:支付授权目录、关联 AppID
· H5 支付:支付域名
· 小程序支付:关联小程序 AppID
商户号必须与业务使用的 AppID 完成绑定,否则会出现「商户号与 appid 不匹配」类错误。


八、常见问题

Q:改了 APIv3 密钥后支付回调失败?
A:所有服务器配置必须同步换成新密钥,并在修改前尽量暂停业务,避免新旧密钥并存导致解密失败。

Q:证书有效期多久?
A:商户 API 证书有效期一般为 5 年,到期前需重新申请并更换私钥与序列号。

Q:v2 已经申请过证书,上 v3 还要重新申请吗?
A:一般不需要;同一套商户 API 证书可用于 v2 / v3,v3 额外需要 APIv3 密钥 + 证书序列号 + 私钥路径。

Q:私钥丢了怎么办?
A:无法找回。需在商户平台作废旧证书后重新申请,并更新后台序列号与私钥文件。


官方文档可参考:微信支付商户文档中心 → APIv3 密钥、申请商户 API 证书。界面若有改版,以商户平台实际菜单为准。

文档目录