结论先行:微信支付 APIv3 是当前官方主推版本,全面改用 JSON 报文、RSA-SHA256 签名与 AES-256-GCM 加密回调。对接的核心是分清三把钥匙——商户私钥负责请求签名、微信支付平台证书或公钥负责验签、APIv3 密钥负责解密回调;小程序前端只做一件事:拿服务端生成并签名的五个参数调 wx.requestPayment,支付结果一律以服务端回调或主动查单为准。回调处理必须验签、解密、幂等落库、正确应答,四步缺一不可。接口与配置细节以微信支付官方最新文档为准。
一、v3 与 v2 的关键差异
| 对比项 | APIv2 | APIv3 |
|---|---|---|
| 报文格式 | XML | JSON |
| 签名算法 | MD5 / HMAC-SHA256 | RSA-SHA256(非对称) |
| 回调报文 | 明文 XML | 加密 JSON(AEAD_AES_256_GCM) |
| 鉴权方式 | 参数内签名 | Authorization 请求头签名 |
| 退款证书 | 需双向 TLS 证书 | 私钥签名即可,无需双向 TLS |
新项目直接按 v3 接入;还在 v2 的团队建议尽快迁移,两套签名体系不要混在同一个工具类里,否则排查签名错误会非常痛苦。
二、三把钥匙的分工
- 商户 API 证书与私钥(apiclient_key.pem):在商户平台「账户中心 - API 安全」申请,私钥用于对每个请求做 RSA-SHA256 签名,证书序列号放进 Authorization 头的 serial_no。私钥丢失只能重新申请,务必离线备份。
- 微信支付平台证书 / 微信支付公钥:用于验证微信应答与回调通知的签名。平台证书会定期轮换,需通过 /v3/certificates 接口自动下载并按序列号缓存;官方现也提供「微信支付公钥」模式,长期有效、免轮换,新接入可优先考虑。
- APIv3 密钥(32 位字符串):在商户平台自行设置,用于解密回调 resource 密文与平台证书下载内容。它与 APIv2 密钥是两个独立配置,混淆会导致回调解密失败。
口诀:商户私钥签名、平台公钥验签、APIv3 密钥解密。拿商户证书去验微信的签名是验不过的,这是新手最常见的错误。
三、服务端下单与两套签名
小程序支付走 JSAPI 下单接口 POST /v3/pay/transactions/jsapi,请求体关键字段:appid、mchid、description、out_trade_no(商户号内唯一)、notify_url(外网可访问、不带参数)、amount.total(单位为分的整数)、payer.openid。金额换算务必用精确十进制运算,禁止 double 乘 100 取整,否则会出现少一分钱的诡异对账差异。
请求鉴权用 Authorization 头,待签名串为五行:HTTP 方法、URL 路径(含 query、不含域名)、时间戳(秒)、随机串、请求体,每行以换行符结尾,空 body 也要保留换行。用商户私钥做 SHA256withRSA 签名后 Base64 编码。
拿到 prepay_id 后还要做第二套签名给前端调起用:待签串是 appId、timeStamp、nonceStr、package(值为 prepay_id=xxx)四行,同样每行换行结尾,再用商户私钥签名得到 paySign。两套签名串完全不同,把下单签名直接当 paySign 用是「签名验证失败」的头号来源。prepay_id 有效期约两小时,过期需用原参数重新下单。
四、回调:验签、解密、幂等、应答
微信支付把结果 POST 到 notify_url,报文 resource 字段是密文。处理顺序固定:
- 验签:用请求头 Wechatpay-Timestamp、Wechatpay-Nonce 与原始报文拼串,按 Wechatpay-Serial 找到对应平台证书或公钥验证 Wechatpay-Signature。不验签等于任何人都能把你的订单改成已支付。
- 解密:用 APIv3 密钥对 resource.ciphertext 做 AES-256-GCM 解密,nonce 与 associated_data 按报文传入,得到含 out_trade_no、transaction_id、trade_state、amount 的明文。
- 校验与幂等:核对商户号、订单号、金额与本地订单一致;用订单状态机加唯一索引做幂等,只有待支付状态才流转为已支付,重复通知直接返回成功。推荐 UPDATE 订单 SET 状态 WHERE 状态为待支付,按影响行数判断是否首次处理。
- 应答:处理成功返回 HTTP 200 或 204;返回非 2xx 或超时,微信会按策略在约 24 小时内多次重推。先落库再应答。
回调不是唯一真相来源:对迟迟未收到回调的订单,服务端应主动调 GET /v3/pay/transactions/out-trade-no/{out_trade_no} 查单兜底;未支付订单及时关单。退款走 /v3/refund/domestic/refunds,out_refund_no 是幂等键,重试必须复用同一单号,退款结果同样以回调或查询为准。
五、小程序前端侧要做什么
前端职责其实很薄,但每一步都有坑:
async payOrder(orderNo) {
const params = await request('/pay/prepay', { orderNo });
wx.requestPayment({
timeStamp: params.timeStamp,
nonceStr: params.nonceStr,
package: params.package,
signType: 'RSA',
paySign: params.paySign,
success: () => this.pollOrderStatus(orderNo),
fail: (err) => {
if (err.errMsg.indexOf('cancel') > -1) {
wx.showToast({ title: '已取消支付', icon: 'none' });
} else {
wx.showToast({ title: '支付失败', icon: 'none' });
}
}
});
}要点:timeStamp 必须是字符串秒级时间戳;signType 在 v3 固定 RSA,抄 v2 的 MD5 必挂;package 必须带 prepay_id= 前缀;success 回调只代表支付流程走完,不代表支付成功,要轮询自家后端查单确认后再跳转成功页;支付按钮做防抖,避免重复下单。另外,交易类小程序需按官方运营规范接入订单发货管理,否则正式环境可能被限制调起支付;个人主体小程序无法开通微信支付。
六、不想自己扛全套?用现成支付配置
证书申请、双签名、回调验签解密、幂等与查单兜底,自建一套的工作量与踩坑成本都不低。中小团队可以把这层交给「api工厂」(https://www.it120.cc/):在后台按帮助中心的「小程序微信支付配置」文档填入商户号与密钥信息,平台服务端完成 v3 下单、签名与回调处理,小程序端用 apifm-wxapi 创建订单后直接拿到调起参数,几行代码拉起收银台,订单状态由平台维护,前端只管查单展示。支付宝支付同样有现成通道。
配置文档入口:https://www.it120.cc/help/index.html 。这样前端与业务后端都不接触商户私钥,密钥管理集中在平台配置里,安全边界更清晰;等团队有余力再考虑自建支付网关也不迟。
文章标签
相关产品
api工厂是面向开发者的开放 SaaS 平台:开箱即用的后台管理系统 + 全端 SDK,只需前端开发即可构建小程序、App、H5 与网站。