跳到主要内容
api工厂
小程序

微信支付 v3 对接要点:证书、签名、回调幂等,前端侧要做什么

api工厂资讯栏目 约 7 分钟阅读
本文由 AI 辅助生成,内容基于公开资讯整理改写,技术细节以官方文档为准。

结论先行:微信支付 APIv3 是当前官方主推版本,全面改用 JSON 报文、RSA-SHA256 签名与 AES-256-GCM 加密回调。对接的核心是分清三把钥匙——商户私钥负责请求签名、微信支付平台证书或公钥负责验签、APIv3 密钥负责解密回调;小程序前端只做一件事:拿服务端生成并签名的五个参数调 wx.requestPayment,支付结果一律以服务端回调或主动查单为准。回调处理必须验签、解密、幂等落库、正确应答,四步缺一不可。接口与配置细节以微信支付官方最新文档为准。

一、v3 与 v2 的关键差异

对比项APIv2APIv3
报文格式XMLJSON
签名算法MD5 / HMAC-SHA256RSA-SHA256(非对称)
回调报文明文 XML加密 JSON(AEAD_AES_256_GCM)
鉴权方式参数内签名Authorization 请求头签名
退款证书需双向 TLS 证书私钥签名即可,无需双向 TLS

新项目直接按 v3 接入;还在 v2 的团队建议尽快迁移,两套签名体系不要混在同一个工具类里,否则排查签名错误会非常痛苦。

二、三把钥匙的分工

  1. 商户 API 证书与私钥(apiclient_key.pem):在商户平台「账户中心 - API 安全」申请,私钥用于对每个请求做 RSA-SHA256 签名,证书序列号放进 Authorization 头的 serial_no。私钥丢失只能重新申请,务必离线备份。
  2. 微信支付平台证书 / 微信支付公钥:用于验证微信应答与回调通知的签名。平台证书会定期轮换,需通过 /v3/certificates 接口自动下载并按序列号缓存;官方现也提供「微信支付公钥」模式,长期有效、免轮换,新接入可优先考虑。
  3. 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 字段是密文。处理顺序固定:

  1. 验签:用请求头 Wechatpay-Timestamp、Wechatpay-Nonce 与原始报文拼串,按 Wechatpay-Serial 找到对应平台证书或公钥验证 Wechatpay-Signature。不验签等于任何人都能把你的订单改成已支付。
  2. 解密:用 APIv3 密钥对 resource.ciphertext 做 AES-256-GCM 解密,nonce 与 associated_data 按报文传入,得到含 out_trade_no、transaction_id、trade_state、amount 的明文。
  3. 校验与幂等:核对商户号、订单号、金额与本地订单一致;用订单状态机加唯一索引做幂等,只有待支付状态才流转为已支付,重复通知直接返回成功。推荐 UPDATE 订单 SET 状态 WHERE 状态为待支付,按影响行数判断是否首次处理。
  4. 应答:处理成功返回 HTTP 200 或 204;返回非 2xx 或超时,微信会按策略在约 24 小时内多次重推。先落库再应答。

回调不是唯一真相来源:对迟迟未收到回调的订单,服务端应主动调 GET /v3/pay/transactions/out-trade-no/{out_trade_no} 查单兜底;未支付订单及时关单。退款走 /v3/refund/domestic/refunds,out_refund_no 是幂等键,重试必须复用同一单号,退款结果同样以回调或查询为准。

五、小程序前端侧要做什么

前端职责其实很薄,但每一步都有坑:

js
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 。这样前端与业务后端都不接触商户私钥,密钥管理集中在平台配置里,安全边界更清晰;等团队有余力再考虑自建支付网关也不迟。

文章标签

微信支付APIv3小程序支付后端对接

相关产品

api工厂是面向开发者的开放 SaaS 平台:开箱即用的后台管理系统 + 全端 SDK,只需前端开发即可构建小程序、App、H5 与网站。

小程序电商拼团砍价

小程序电商营销玩法:拼团、砍价、分销的业务逻辑与技术实现

拼团的核心是团状态机与超时退款,砍价的核心是底价控制与防刷,分销的核心是关系链绑定与佣金结算时点。三种玩法都有成熟实现,用现成插件加开源商城模板,几天就能上线验证。

小程序约 5 分钟阅读
微信小程序订阅消息用户召回

小程序订阅消息与用户召回:模板消息退场后的合规触达

订阅消息的本质是把触达选择权还给用户:一次授权一条消息,营销式群发走不通。正确做法是在下单、预约等关键节点顺势请求授权,服务端管理订阅额度,用服务通知加短信、会员权益做合规召回组合。

小程序约 6 分钟阅读