做微信生态开发支付是绕不开的一环。微信小程序支付和微信浏览器支付这两年我经手的项目没有二十个也有十五个从最初的公众号H5到小程序商城再到外部浏览器唤起微信支付踩过的坑零零碎碎攒了一堆。这篇想把整个支付接入的脉络整理清楚从场景选型到参数签名从下单到回调验签从uniapp跨端适配到线上问题排查基本覆盖一个支付模块从零到上线的全部必经之路也给准备接微信支付的同学一条能直接照着做的路线图。1. 微信支付场景全景与方案选型很多新手容易把“微信支付”当成一个接口来用实际上微信支付是一整套场景化方案。先搞清楚自己处在哪个场景再决定调哪个接口不然就会出现“明明代码对着文档写的就是调不起来”的情况。1.1 支付场景地图JSAPI、H5、Native、App微信支付官方把支付产品拆成了几大方向我们平时最常打交道的其实是下面这些产品使用场景调起方式关键前置JSAPI支付微信小程序内、微信公众号内、微信内置浏览器打开的H5页面小程序用 wx.requestPayment微信内H5用 WeixinJSBridge 或 wx.chooseWXPay必须有用户的 openid且页面运行在微信客户端内微信H5支付手机浏览器、App内嵌WebView用户不在微信内后端返回 h5_url前端302跳转由微信客户端拦截唤起需要配置H5支付域名必须在非微信浏览器内使用Native支付PC扫码支付生成二维码用户用微信扫同步/异步回调结合确认结果App支付iOS/Android App 内调起微信客户端SDK需要开放平台移动应用包名签名匹配这段表格信息密度很大我建议先背下来。我们通常说的“微信浏览器支付”其实属于JSAPI支付的大类里只是页面载体跑在微信内置浏览器上支付本身还是要走JSAPI那一套参数逻辑。而“微信小程序支付”虽然也属于JSAPI但openid的获取方式、前端调起接口和后端接口URL又有区别。1.2 方案选型背后的三个原则干了这几年我自己总结出三个选型原则基本能应对90%的需求判断。第一用户当前在哪个环境。用户在小程序里支付只能走小程序支付用户在微信公众号H5里支付就用公众号JSAPI用户压根不在微信里还非得用微信支付就只有微信H5支付可选。这里有个最容易踩的坑不要在微信内置浏览器里跳转微信H5支付的 h5_url微信会直接拦截提示“无法验证参数”或者“当前页面无法支付”因为微信内只允许JSAPI产品线跑。第二支付参数是否依赖openid。JSAPI系列强依赖openid所以凡是没登录微信的场景第一步一定是先拿到用户的身份标识。而微信H5支付和Native支付不依赖openid走的是“拉起收银台”路线扫码或跳转后由用户自己确认。第三钱款校验放在哪一层。无论哪一种场景下单和回调的核心逻辑都高度一致无非是 trade_type、下单URL、前端唤起参数不同。所以我不建议每个场景各写一套支付模块而是做一套“支付网关”对外暴露统一的下单和回调入口内部再按场景路由到微信对应的接口。这个思路后期维护成本极低多做几个项目就明白有多省事。2. 支付接入前的四件套准备很多第一次接微信支付的同学死在“前置条件”上。微信支付的接入不像普通API那样拿个Key就行它有一整套账号体系与安全体系理解这套关系后面所有报错都会好排查得多。2.1 商户号、AppID、密钥、证书之间是什么关系微信支付涉及的账号主体总共有四个东西关系可以类比成“银行卡 身份证 签名笔 临时令牌”商户号mchid收款主体的唯一标识相当于银行账号。你在微信支付商户平台开店后就有。AppID小程序或公众号的唯一标识相当于收款终端所在的“店面编号”。商户号必须和AppID完成绑定支付才能拉起这个绑定在商户平台的产品中心里操作。APIv3密钥自己设置的一串32位密钥用于回调通知里解密支付结果数据。它不参与下单签名很多人搞混了。商户API证书由商户平台下载的一组密钥文件apiclient_key.pem / apiclient_cert.pem下单请求时用来做客户端签名。这里必须强调商户号与AppID的绑定关系是所有“签名验证失败”“商户号与AppID不匹配”的根源之一。换了个小程序AppID换了但商户号没去绑定或者绑定错了支付一秒都起不来。2.2 域名与回调地址的配置细节支付模块跑通需要配三类域名每一类都容易出错小程序后台的 request 合法域名所有小程序内发起的HTTPS请求都必须在这里登记否则真机上会直接 fail。公众号网页授权域名公众号H5获取openid时OAuth2的 redirect_uri 域名必须在这个白名单里。注意这个域名不能带路径只能填到顶级域名或二级域名。微信支付商户平台的支付授权目录JSAPI支付要求在商户平台配置一个目录比如https://api.yourdomain.com/pay/实际下单页面的URL必须在这个目录下否则会报“当前页面的URL未注册”。还有一个容易被忽略的细节支付回调地址 notify_url 用HTTPS地址且不能带参数。回调地址和支付授权目录并不保证是同一个回调地址只要在公网可访问即可但必须能被微信服务器请求到内网IP、localhost、非标准端口通通不行。2.3 API v2和v3到底用哪套微信支付目前主推APIv3新接入商户默认建议直接上v3部分老项目还在用v2。两者的核心差异我用一张表说明白对比项APIv2APIv3请求签名MD5/HMAC-SHA256 API密钥商户私钥RSA-SHA256 Authorization头回调验签通过API密钥做MD5校验用微信支付平台证书验签数据用APIv3密钥AES-GCM解密报文格式XMLJSON参数组织所有字段参与签名请求体在Authorization签名之外签名针对消息摘要维护状态老商户逐渐迁移新功能新需求基本都在v3我的建议很简单新项目一律v3老项目除非被平台强制迁移不然可以先不折腾。v3签名虽然看起来复杂但它把签名和通信拆开了排查问题的思路清楚很多。3. 微信小程序支付从下单到回调的完整实现小程序支付是整个微信支付体系里最常用的一条链路。很多教程把这段写得不痛不痒我尽量把关键代码和关键坑都摆出来。3.1 前置openid获取与登录态设计小程序支付要先把用户身份换成 openid。我们常说的 wx.login 拿 code后端拿 code 去https://api.weixin.qq.com/sns/jscode2session换 openid 和 session_key这个就是链路起点。我踩过的坑是把 openid 存在了前端缓存里然后服务端下单时从请求参数里取 openid结果用户换了个微信或者缓存被清openid 对不上号。正确做法是登录成功后服务端把 openid 与业务用户ID绑定并在服务端维护登录态比如自定义token。下单时前端不传 openid后端根据token查到 openid 再下单这样安全性和一致性都稳。3.2 服务端统一下单与签名v3下单接口是POST https://api.mch.weixin.qq.com/v3/pay/transactions/jsapi请求体长这样{ appid: wx1234567890abcdef, mchid: 1900000001, description: 商品描述-测试订单, out_trade_no: 20250115103245001, notify_url: https://api.yourdomain.com/pay/notify, amount: { total: 1, currency: CNY }, payer: { openid: oUpF8uMuAJO_M2pxb1Q9zNjWeS6o } }注意金额单位是“分”整数类型不是元也不是浮点数。很多资损事故就是这里把单位搞错了1元写成1实际扣了1分或者把分写成元订单直接贵了100倍。请求Header的Authorization需要组一段特定格式的签名串。签名串的生成方式我用PHP示例说明逻辑理解后换任何语言都一样$mchid 1900000001; $serialNo 你的商户证书序列号; $privateKey openssl_pkey_get_private(file://apiclient_key.pem); $nonceStr bin2hex(random_bytes(16)); $timestamp time(); $url /v3/pay/transactions/jsapi; $body json_encode($requestBody, JSON_UNESCAPED_UNICODE); $message POST\n{$url}\n{$timestamp}\n{$nonceStr}\n{$body}\n; openssl_sign($message, $rawSignature, $privateKey, sha256WithRSAEncryption); $signature base64_encode($rawSignature); $authorization sprintf( WECHATPAY2-SHA256-RSA2048 mchid%s,nonce_str%s,timestamp%d,serial_no%s,signature%s, $mchid, $nonceStr, $timestamp, $serialNo, $signature );这段代码里最容易写错的是$message最后必须带一个换行符且换行符是\n不是PHP双引号没解析出来的\n。我见过不下五次因为拼接字符串时少了一个换行导致微信服务端验签失败返回401。下单成功后会返回 prepay_id。这里要提醒一句prepay_id 的有效期是2小时但微信官方建议不要提前太久生成通常用户点击支付时实时下单最稳。3.3 前端 wx.requestPayment 唤起收银台小程序端拿到 prepay_id 之后还需要后端再对前端参数做一次签名因为前端发起支付时需要的参数和后端下单时完全不同。后端返回给前端的结构类似{ timeStamp: 1736900000, nonceStr: 9d0e7b1a5c3f4e8a, package: prepay_idwx081234567890abcdef, signType: RSA, paySign: 基于商户私钥与上面几项生成的RSA-SHA256签名 }paySign 的待签名串是appId\n timeStamp\n nonceStr\n package\n再强调一次这里的待签名串是四个部分用\n分隔最后 package 后面也有一个\n顺序必须是 appId、timeStamp、nonceStr、package不要自己改成别的顺序否则前端就会报“用户态签名signature错误”。前端调用wx.requestPayment({ timeStamp: res.data.timeStamp, nonceStr: res.data.nonceStr, package: res.data.package, signType: res.data.signType, paySign: res.data.paySign, success: (result) { // 这里只代表用户完成了官方收银台流程不代表钱一定到账 // 最终以服务端回调结果为准 }, fail: (err) { // 用户取消、签名错误都会走这里 } });这里有个必须要讲的点success回调并不等于支付成功。用户输错密码、余额不足、被风控拦截都可能让前端看起来“支付完成”但实际没扣款。正确的业务处理一定是以后端收到的异步通知为准前端只做页面跳转和订单状态刷新。3.4 回调验签与订单落库微信支付成功后会向 notify_url 发起POST回调v3的回调报文长这样{ id: EV-20250115000000001, event_type: TRANSACTION.SUCCESS, resource_type: encrypt-resource, resource: { ciphertext: 加密的支付结果, nonce: 加密随机串, associated_data: 附加数据 } }resource.ciphertext是 AES-256-GCM 加密的数据解密用的 key 就是 APIv3密钥不是商家私钥。解密后得到的明文包含 out_trade_no、transaction_id、amount、payer 等信息流程上要做四件事用微信支付平台证书或平台公钥验证回调请求的签名。解密 ciphertext拿到明文结果。检查 out_trade_no 是否在自己的订单表里且订单状态是否未支付防重复回调做幂等。比较明文里的 total_fee 和下单时的金额是否完全一致。如果不一致基本可以断定是恶意伪造或数据异常直接拒绝。处理完业务后必须返回固定格式的应答{ code: SUCCESS, message: 成功 }如果不返回这个微信会按照一定的时间策略重复通知直到超时。所以回调接口一定要做成“可重入”的收到回调先查订单状态如果已经是已支付了直接返回成功不要再去改库和加积分否则线上会出现“同一笔订单被处理两次”的资损事故。4. 微信浏览器内的JSAPI支付微信浏览器支付和微信小程序支付在原理上同根同源但页面载体和身份获取方式完全不同。这里重点讲差异点。4.1 微信内H5页面支付与小程序支付的异同同一套支付接口路由下小程序支付和公众号H5支付只是 appid 不同、openid 获取方式不同但后端统一下单的接口都是同一个 v3/pay/transactions/jsapi回调逻辑也基本一致。差异点主要体现在三个地方维度小程序支付微信浏览器/公众号H5支付身份获取wx.login code2sessionOAuth2网页授权 snsapi_base前端唤起wx.requestPaymentwx.chooseWXPay 或 WeixinJSBridge.invoke页面载体小程序原生页面HTML页面授权配置小程序后台 request 域名公众号后台网页授权域名 支付授权目录一个容易忽略的坑公众号下如果有多个应用不同应用需要不同的 AppID但可以用同一个商户号前提是商户号与每个 AppID 都绑定。开发时我习惯把 appid 和支付配置单独做成一个配置项避免在一个项目里切换环境时把 AppID 写乱。4.2 OAuth2获取openid在微信内置浏览器里获取 openid 的路径是网页授权。用一个很简单的流程前端跳转到https://open.weixin.qq.com/connect/oauth2/authorize?appidxxxredirect_urixxxresponse_typecodescopesnsapi_base#wechat_redirect微信会带着 code 跳回 redirect_uri后端拿 code 换 openid。snsapi_base 类型静默授权用户无感知不需要用户手动点击同意。如果是敏感操作才需要 snsapi_userinfo。做支付建议一律用 snsapi_base不要为了提高“用户画像完整度”去申请用户信息授权那是另一套审核路径容易卡。这里有个极其典型的问题redirect_uri 必须事先在公众号后台配置为“网页授权域名”的完全匹配地址。比如配置了https://api.yourdomain.com/pay那 redirect_uri 就只能是这个地址或其子路径。如果前端跳转时把参数加在域名后面拼成了另一个地址微信公众号会直接报“redirect_uri参数错误”。4.3 调起支付的两种姿势wx.chooseWXPay 与 WeixinJSBridge微信浏览器内调起支付目前主流有两种方式。第一种是通过微信JSSDK。需要先引入 JSSDK 脚本然后配置wx.config签名用的 jsapi_ticket 由后端通过接口获取再调wx.chooseWXPaywx.chooseWXPay({ timestamp: res.data.timeStamp, nonceStr: res.data.nonceStr, package: res.data.package, signType: res.data.signType, paySign: res.data.paySign, success: function (result) { // 用户完成支付 } });这里的参数和小程序的 wx.requestPayment 几乎一样实际上微信JSAPI支付的下单返回参数就是同一套区别只是前端环境不同。第二种是直接用内置的 WeixinJSBridge不需要引入 JSSDK。这里有个细节老版本代码一般写WeixinJSBridge.invoke(getBrandWCPayRequest, { appId: res.data.appId, timeStamp: res.data.timeStamp, nonceStr: res.data.nonceStr, package: res.data.package, signType: res.data.signType, paySign: res.data.paySign }, function (res) { if (res.err_msg get_brand_wcpay_request:ok) { // 支付完成 } });注意 WeixinJSBridge 版本里多了一个appId字段而 JSSDK 的 chooseWXPay 不需要 appId。实际开发中我更推荐用 JSSDK因为它是官方文档主推、前后兼容性好遇到 bridgeReady 处理起来也比较稳定。4.4 关于“伪造微信浏览器UA”的风险说明很多外部H5页面被要求在微信内打开有人会想我改一下浏览器标识UA伪装成微信是不是就能直接调起支付这里必须泼一盆冷水。微信支付的安全性依赖微信客户端内的JSAPI核心能力UA识别只是前端展示层的判断真正调起支付还需要微信客户端提供的 native 能力通道。光改UA后端拿不到 openidWeixinJSBridge 接口也不存在所以不可能绕过支付限制。换个角度说如果你做的是“外部浏览器唤起微信支付”那就不需要伪造UA应该老老实实走微信H5支付接口。UA伪装这种思路在支付链路里注定是死路一条别再浪费时间研究。5. 外部浏览器唤起微信微信H5支付如果用户不在微信客户端里还想用微信支付唯一正路就是微信H5支付产品名就是“微信H5支付”。这个场景在电商、体验类H5活动、App内WebView里很常见。5.1 什么时候必须用H5支付判断条件很直接用户是在微信外浏览器打开的页面又选择“微信支付”此时必须用H5支付。如果用户已经在微信内这套方案反而用不了因为微信会拦截。很多同学会遇到一个迷惑场景用户在百度搜索进入一个H5商城点击微信支付后页面跳到一个看起来像微信官方的确认支付页然后自动唤起微信。这就是微信H5支付的完整表现。它通过后端下单返回一个h5_url前端302跳转到这个地址微信客户端识别到该URL后自动拉起收银台。5.2 H5支付下单与跳转H5下单接口是POST https://api.mch.weixin.qq.com/v3/pay/transactions/h5请求体比JSAPI多一个scene_info{ appid: wx1234567890abcdef, mchid: 1900000001, description: H5订单测试, out_trade_no: 20250115123200001, notify_url: https://api.yourdomain.com/pay/notify, amount: { total: 100, currency: CNY }, scene_info: { payer_client_ip: 116.25.46.188, h5_info: { type: Wap, wap_url: https://h5.yourdomain.com, wap_name: 你的商城名称 } } }payer_client_ip是用户的真实IPv4地址很多项目直接填服务端IP或空值这个字段在风控上非常重要建议从前端请求头里透传。wap_name会展示在微信支付确认页里需要与你的商户主体经营范围保持一致否则可能被风控拦截。下单成功返回h5_url后端直接重定向header(Location: . $h5Url, true, 302);如果是前后端分离架构也可以直接把h5_url返回给前端由前端window.location.href跳转。注意这个地址不要做短链、不要套一层自己的跳转参数微信会校验来源和时效性。5.3 H5支付的限制与合规红线H5支付有一些硬性限制第一次接入很容易被坑必须配置 H5支付域名。商户平台里要添加发起支付的页面域名跳转的h5_url与配置域名要能对应上。微信内禁止使用。官方文档明确写了H5支付只能在微信外部浏览器使用微信内必须走JSAPI。所以业务方要做环境判断微信内显示“请使用微信内置浏览器打开后支付”否则用户看到的会是一个无法闭环的报错页。有风控意识。H5支付在非微信环境下用户身份无法通过openid直接识别微信的风控会比较严格。同一设备频繁更换订单、团伙批量注册下单、用代理IP混淆位置都可能被判定为可疑交易而被拦截。支付网关如果同时接了微信JSAPI和微信H5支付我建议回调地址用同一个因为两者回调的报文字段结构完全一致后端处理逻辑不需要拆分。6. 跨端项目uniapp的支付差异现在很多项目是uniapp做的一套代码编小程序、App、H5。支付这个模块到了跨端场景下特别注意前端API统一了但底层参数并不统一。6.1 小程序端与App端支付参数的差异uniapp 里调起支付用的是uni.requestPayment但 provider 和参数结构在小程序端和App端完全不同。小程序端微信小程序运行环境uni.requestPayment({ provider: wxpay, timeStamp: 1736900000, nonceStr: xxx, package: prepay_idxxx, signType: RSA, paySign: xxx, success: function (res) {} });App端打包成 Android/iOS 应用后uni.requestPayment({ provider: wxpay, orderInfo: orderInfoStr, success: function (res) {} });App端这里不是传 timeStamp、paySign 这些键值对而是传一个由后端拼接好的orderInfo字符串。这个字符串在Android端是微信SDK要求的 orderInfo 格式iOS端同样需要用 SDK 能识别的结构不能拿小程序端的参数硬套。所以我给团队定的规矩是支付参数组装绝不做在前端而是由后端根据客户端类型分别返回对应字段。小程序端返回小程序参数App端返回App的orderInfoH5端返回跳转URL或者JSSDK参数。前端不重复造轮子只负责判断当前运行环境、然后取对应参数调起。6.2 几个容易踩的跨端支付坑第一个坑是 App 端顺序。App 调起微信支付前需要先确认微信是否安装以及是否已经在开放平台申请了移动应用并拿到了App的 appid。很多人只在小程序后台配置了AppID忘了开放平台注册移动应用结果App端怎么调都提示“微信未安装或版本过低”。第二个坑是调用时机。站在用户点击支付按钮到支付成功之间的这段时间请求可能非常频繁。跨端项目里H5和App场景很容易出现用户返回页面后再次点击支付导致重复下单。我的方案是下单前加一个幂等键前端每次进支付页生成一个 transaction_id后端对同一个 transaction_id 只允许创建一笔未支付订单重复请求直接返回老订单从根上杜绝重复扣款风险。第三个坑是回调地址不能区分端。App支付、小程序支付、H5支付的回调报文结构一致后端收到回调后不要试图通过报文里的某个字段判断“这笔单来自哪个端”而是应该用自己数据库里的订单记录判断业务状态。订单表里存订单来源字段回调更新状态时只处理这一条记录。7. 高频报错与线上问题排查支付上线后真正消耗精力的不是写代码而是各种莫名其妙的线上报错。我把这些年遇到的、以及身边同行反馈过的高频问题整理成了一个排查手册。7.1 用户态签名signature错误这个问题在小程序和公众号H5支付里非常高频报错通常来自前端调起收银台时的paySign校验不过。排查思路分四步检查待签名串顺序。必须是appId\n timeStamp\n nonceStr\n package\npackage 的值一定带prepay_id前缀。检查签名算法。v3接口下前端 paySign 用 RSA-SHA256对的但很多老项目v2还在用 MD5对照报错信息里的 signType 去查。如果后端返回的是signType: MD5前端却按 RSA 验签必然失败。检查换行符。拼接签名串时确认每个字段后面都有真实的换行符不是反斜杠n字符串。检查拿到的 prepay_id 对应下单接口版本。用v3接口下单返回的 prepay_id 在调起时却配了v2参数签名体系就完全错位了。7.2 iOS小程序网络请求失败6001“6001”在小程序网络报错里几乎成了iOS专有名场面。表现是同一份代码安卓正常iOS真机偶发请求失败错误码时不时是6001。这个真不一定是支付问题而是小程序网络请求底层的问题。常见诱因三个后端HTTPS证书链不完整iOS的NSURLSession要求证书链必须完整闭合缺失中间证书就握手失败。服务器只支持 HTTP/1.1 不支持部分 TLS 版本iOS在弱网或 IPv6 环境下协商失败。请求并发过高时小程序端内存被撑爆复用到支付流程时表现成接口偶发失败。排查路径开发者工具一般复现不了必须 iOS 真机打开调试模式配合“vConsole 看 request 返回的状态码和错误消息”反复切换飞行模式触发弱网再定位是 TLS 还是并发问题。我最后常用的解决手段是整体用wx.request封装统一拦截器重试逻辑里区分“网络不可达”和“业务失败”6001统一做一次请求级重试能挡住大半偶发故障。7.3 苹果虚拟支付与IAP退款在小程序里卖会员、卖课程、卖虚拟道具属于虚拟支付范畴。苹果的规则很明确iOS端虚拟商品必须通过 IAP苹果内购走微信小程序里用微信支付卖虚拟商品属于违规轻则审核被打回重则整个虚拟支付能力被限制。所以如果项目涉及虚拟商品支付产品设计要在前端提前分端分流iOS端走 IAP安卓和微信H5端走微信支付。这里还有个很烦的问题用户走 IAP 购买后申请退款苹果会通过App Store Server API推送退款通知服务端必须监听退款事件并主动回收用户已发放的虚拟权益。很多第一次做虚拟商品的同学忘了这一步结果用户白白退款还拿着VIP这就是纯资损了。7.4 年审、导航栏高度、请求封装等运营开发细节做微信生态支付旁边总有一堆非支付但影响体验的“邻居问题”。这里顺手记录几个高频关键词对应的方案。微信小程序年审这块主体认证到期后小程序功能不受影响但部分类目和接口权限可能被收紧。支付本身不依赖年审但如果支付页面涉及需要特定类目的业务功能年审过期可能导致审核类目失效。建议把年审时间记在运营日历里提前一个月准备续期资料。顶部导航栏高度的话题在小程序里一直有热度尤其做自定义导航栏时。不同机型的状态栏高度不一样官方提供了wx.getWindowInfo()或wx.getMenuButtonBoundingClientRect()拿胶囊位置。最稳的做法是拿到胶囊的顶部和底部坐标然后用它反推导航栏的安全高度不要硬编码数值否则iPhone和安卓横竖屏一换就裂开。请求封装这个点把uni.request或wx.request封装成统一拦截器是支付项目的基本功。我一般会在拦截器里做四件事统一拼接token、统一处理服务端错误码、对支付类接口做特殊透传、超时和网络错误自动重试。这样支付流程的代码会变得干净很多排查问题时也能一眼看到请求在哪一步丢了。最后再分享一个我自己的习惯这几年做支付项目我最深的一个体会是支付本身并不难难的永远是交易闭环和异常处理。所以我从第二个支付项目开始就定了一条铁律——所有的交易状态流转以数据库为准前端展示永远只作为辅助信息。用户看到的“支付成功”弹窗只是提示后端回调落库后才是真正的成功。我甚至在回调里还会再做一次“主动查单”回调成功后立即调用微信支付查单接口确认最终状态双重校验后才更新订单。这套做法帮我挡过不少线上资损。如果你正在负责支付模块我建议你也把“下单幂等、回调幂等、金额二次校验”这三道防线提前做成基础设施而不是等出了问题再补。支付是直接碰钱的地方每一次线上失误代价都不小。希望这篇折腾出来的经验能让你少踩几个坑。 微信支付接入全攻略：从场景选型到回调验签与线上排查
做微信生态开发支付是绕不开的一环。微信小程序支付和微信浏览器支付这两年我经手的项目没有二十个也有十五个从最初的公众号H5到小程序商城再到外部浏览器唤起微信支付踩过的坑零零碎碎攒了一堆。这篇想把整个支付接入的脉络整理清楚从场景选型到参数签名从下单到回调验签从uniapp跨端适配到线上问题排查基本覆盖一个支付模块从零到上线的全部必经之路也给准备接微信支付的同学一条能直接照着做的路线图。1. 微信支付场景全景与方案选型很多新手容易把“微信支付”当成一个接口来用实际上微信支付是一整套场景化方案。先搞清楚自己处在哪个场景再决定调哪个接口不然就会出现“明明代码对着文档写的就是调不起来”的情况。1.1 支付场景地图JSAPI、H5、Native、App微信支付官方把支付产品拆成了几大方向我们平时最常打交道的其实是下面这些产品使用场景调起方式关键前置JSAPI支付微信小程序内、微信公众号内、微信内置浏览器打开的H5页面小程序用 wx.requestPayment微信内H5用 WeixinJSBridge 或 wx.chooseWXPay必须有用户的 openid且页面运行在微信客户端内微信H5支付手机浏览器、App内嵌WebView用户不在微信内后端返回 h5_url前端302跳转由微信客户端拦截唤起需要配置H5支付域名必须在非微信浏览器内使用Native支付PC扫码支付生成二维码用户用微信扫同步/异步回调结合确认结果App支付iOS/Android App 内调起微信客户端SDK需要开放平台移动应用包名签名匹配这段表格信息密度很大我建议先背下来。我们通常说的“微信浏览器支付”其实属于JSAPI支付的大类里只是页面载体跑在微信内置浏览器上支付本身还是要走JSAPI那一套参数逻辑。而“微信小程序支付”虽然也属于JSAPI但openid的获取方式、前端调起接口和后端接口URL又有区别。1.2 方案选型背后的三个原则干了这几年我自己总结出三个选型原则基本能应对90%的需求判断。第一用户当前在哪个环境。用户在小程序里支付只能走小程序支付用户在微信公众号H5里支付就用公众号JSAPI用户压根不在微信里还非得用微信支付就只有微信H5支付可选。这里有个最容易踩的坑不要在微信内置浏览器里跳转微信H5支付的 h5_url微信会直接拦截提示“无法验证参数”或者“当前页面无法支付”因为微信内只允许JSAPI产品线跑。第二支付参数是否依赖openid。JSAPI系列强依赖openid所以凡是没登录微信的场景第一步一定是先拿到用户的身份标识。而微信H5支付和Native支付不依赖openid走的是“拉起收银台”路线扫码或跳转后由用户自己确认。第三钱款校验放在哪一层。无论哪一种场景下单和回调的核心逻辑都高度一致无非是 trade_type、下单URL、前端唤起参数不同。所以我不建议每个场景各写一套支付模块而是做一套“支付网关”对外暴露统一的下单和回调入口内部再按场景路由到微信对应的接口。这个思路后期维护成本极低多做几个项目就明白有多省事。2. 支付接入前的四件套准备很多第一次接微信支付的同学死在“前置条件”上。微信支付的接入不像普通API那样拿个Key就行它有一整套账号体系与安全体系理解这套关系后面所有报错都会好排查得多。2.1 商户号、AppID、密钥、证书之间是什么关系微信支付涉及的账号主体总共有四个东西关系可以类比成“银行卡 身份证 签名笔 临时令牌”商户号mchid收款主体的唯一标识相当于银行账号。你在微信支付商户平台开店后就有。AppID小程序或公众号的唯一标识相当于收款终端所在的“店面编号”。商户号必须和AppID完成绑定支付才能拉起这个绑定在商户平台的产品中心里操作。APIv3密钥自己设置的一串32位密钥用于回调通知里解密支付结果数据。它不参与下单签名很多人搞混了。商户API证书由商户平台下载的一组密钥文件apiclient_key.pem / apiclient_cert.pem下单请求时用来做客户端签名。这里必须强调商户号与AppID的绑定关系是所有“签名验证失败”“商户号与AppID不匹配”的根源之一。换了个小程序AppID换了但商户号没去绑定或者绑定错了支付一秒都起不来。2.2 域名与回调地址的配置细节支付模块跑通需要配三类域名每一类都容易出错小程序后台的 request 合法域名所有小程序内发起的HTTPS请求都必须在这里登记否则真机上会直接 fail。公众号网页授权域名公众号H5获取openid时OAuth2的 redirect_uri 域名必须在这个白名单里。注意这个域名不能带路径只能填到顶级域名或二级域名。微信支付商户平台的支付授权目录JSAPI支付要求在商户平台配置一个目录比如https://api.yourdomain.com/pay/实际下单页面的URL必须在这个目录下否则会报“当前页面的URL未注册”。还有一个容易被忽略的细节支付回调地址 notify_url 用HTTPS地址且不能带参数。回调地址和支付授权目录并不保证是同一个回调地址只要在公网可访问即可但必须能被微信服务器请求到内网IP、localhost、非标准端口通通不行。2.3 API v2和v3到底用哪套微信支付目前主推APIv3新接入商户默认建议直接上v3部分老项目还在用v2。两者的核心差异我用一张表说明白对比项APIv2APIv3请求签名MD5/HMAC-SHA256 API密钥商户私钥RSA-SHA256 Authorization头回调验签通过API密钥做MD5校验用微信支付平台证书验签数据用APIv3密钥AES-GCM解密报文格式XMLJSON参数组织所有字段参与签名请求体在Authorization签名之外签名针对消息摘要维护状态老商户逐渐迁移新功能新需求基本都在v3我的建议很简单新项目一律v3老项目除非被平台强制迁移不然可以先不折腾。v3签名虽然看起来复杂但它把签名和通信拆开了排查问题的思路清楚很多。3. 微信小程序支付从下单到回调的完整实现小程序支付是整个微信支付体系里最常用的一条链路。很多教程把这段写得不痛不痒我尽量把关键代码和关键坑都摆出来。3.1 前置openid获取与登录态设计小程序支付要先把用户身份换成 openid。我们常说的 wx.login 拿 code后端拿 code 去https://api.weixin.qq.com/sns/jscode2session换 openid 和 session_key这个就是链路起点。我踩过的坑是把 openid 存在了前端缓存里然后服务端下单时从请求参数里取 openid结果用户换了个微信或者缓存被清openid 对不上号。正确做法是登录成功后服务端把 openid 与业务用户ID绑定并在服务端维护登录态比如自定义token。下单时前端不传 openid后端根据token查到 openid 再下单这样安全性和一致性都稳。3.2 服务端统一下单与签名v3下单接口是POST https://api.mch.weixin.qq.com/v3/pay/transactions/jsapi请求体长这样{ appid: wx1234567890abcdef, mchid: 1900000001, description: 商品描述-测试订单, out_trade_no: 20250115103245001, notify_url: https://api.yourdomain.com/pay/notify, amount: { total: 1, currency: CNY }, payer: { openid: oUpF8uMuAJO_M2pxb1Q9zNjWeS6o } }注意金额单位是“分”整数类型不是元也不是浮点数。很多资损事故就是这里把单位搞错了1元写成1实际扣了1分或者把分写成元订单直接贵了100倍。请求Header的Authorization需要组一段特定格式的签名串。签名串的生成方式我用PHP示例说明逻辑理解后换任何语言都一样$mchid 1900000001; $serialNo 你的商户证书序列号; $privateKey openssl_pkey_get_private(file://apiclient_key.pem); $nonceStr bin2hex(random_bytes(16)); $timestamp time(); $url /v3/pay/transactions/jsapi; $body json_encode($requestBody, JSON_UNESCAPED_UNICODE); $message POST\n{$url}\n{$timestamp}\n{$nonceStr}\n{$body}\n; openssl_sign($message, $rawSignature, $privateKey, sha256WithRSAEncryption); $signature base64_encode($rawSignature); $authorization sprintf( WECHATPAY2-SHA256-RSA2048 mchid%s,nonce_str%s,timestamp%d,serial_no%s,signature%s, $mchid, $nonceStr, $timestamp, $serialNo, $signature );这段代码里最容易写错的是$message最后必须带一个换行符且换行符是\n不是PHP双引号没解析出来的\n。我见过不下五次因为拼接字符串时少了一个换行导致微信服务端验签失败返回401。下单成功后会返回 prepay_id。这里要提醒一句prepay_id 的有效期是2小时但微信官方建议不要提前太久生成通常用户点击支付时实时下单最稳。3.3 前端 wx.requestPayment 唤起收银台小程序端拿到 prepay_id 之后还需要后端再对前端参数做一次签名因为前端发起支付时需要的参数和后端下单时完全不同。后端返回给前端的结构类似{ timeStamp: 1736900000, nonceStr: 9d0e7b1a5c3f4e8a, package: prepay_idwx081234567890abcdef, signType: RSA, paySign: 基于商户私钥与上面几项生成的RSA-SHA256签名 }paySign 的待签名串是appId\n timeStamp\n nonceStr\n package\n再强调一次这里的待签名串是四个部分用\n分隔最后 package 后面也有一个\n顺序必须是 appId、timeStamp、nonceStr、package不要自己改成别的顺序否则前端就会报“用户态签名signature错误”。前端调用wx.requestPayment({ timeStamp: res.data.timeStamp, nonceStr: res.data.nonceStr, package: res.data.package, signType: res.data.signType, paySign: res.data.paySign, success: (result) { // 这里只代表用户完成了官方收银台流程不代表钱一定到账 // 最终以服务端回调结果为准 }, fail: (err) { // 用户取消、签名错误都会走这里 } });这里有个必须要讲的点success回调并不等于支付成功。用户输错密码、余额不足、被风控拦截都可能让前端看起来“支付完成”但实际没扣款。正确的业务处理一定是以后端收到的异步通知为准前端只做页面跳转和订单状态刷新。3.4 回调验签与订单落库微信支付成功后会向 notify_url 发起POST回调v3的回调报文长这样{ id: EV-20250115000000001, event_type: TRANSACTION.SUCCESS, resource_type: encrypt-resource, resource: { ciphertext: 加密的支付结果, nonce: 加密随机串, associated_data: 附加数据 } }resource.ciphertext是 AES-256-GCM 加密的数据解密用的 key 就是 APIv3密钥不是商家私钥。解密后得到的明文包含 out_trade_no、transaction_id、amount、payer 等信息流程上要做四件事用微信支付平台证书或平台公钥验证回调请求的签名。解密 ciphertext拿到明文结果。检查 out_trade_no 是否在自己的订单表里且订单状态是否未支付防重复回调做幂等。比较明文里的 total_fee 和下单时的金额是否完全一致。如果不一致基本可以断定是恶意伪造或数据异常直接拒绝。处理完业务后必须返回固定格式的应答{ code: SUCCESS, message: 成功 }如果不返回这个微信会按照一定的时间策略重复通知直到超时。所以回调接口一定要做成“可重入”的收到回调先查订单状态如果已经是已支付了直接返回成功不要再去改库和加积分否则线上会出现“同一笔订单被处理两次”的资损事故。4. 微信浏览器内的JSAPI支付微信浏览器支付和微信小程序支付在原理上同根同源但页面载体和身份获取方式完全不同。这里重点讲差异点。4.1 微信内H5页面支付与小程序支付的异同同一套支付接口路由下小程序支付和公众号H5支付只是 appid 不同、openid 获取方式不同但后端统一下单的接口都是同一个 v3/pay/transactions/jsapi回调逻辑也基本一致。差异点主要体现在三个地方维度小程序支付微信浏览器/公众号H5支付身份获取wx.login code2sessionOAuth2网页授权 snsapi_base前端唤起wx.requestPaymentwx.chooseWXPay 或 WeixinJSBridge.invoke页面载体小程序原生页面HTML页面授权配置小程序后台 request 域名公众号后台网页授权域名 支付授权目录一个容易忽略的坑公众号下如果有多个应用不同应用需要不同的 AppID但可以用同一个商户号前提是商户号与每个 AppID 都绑定。开发时我习惯把 appid 和支付配置单独做成一个配置项避免在一个项目里切换环境时把 AppID 写乱。4.2 OAuth2获取openid在微信内置浏览器里获取 openid 的路径是网页授权。用一个很简单的流程前端跳转到https://open.weixin.qq.com/connect/oauth2/authorize?appidxxxredirect_urixxxresponse_typecodescopesnsapi_base#wechat_redirect微信会带着 code 跳回 redirect_uri后端拿 code 换 openid。snsapi_base 类型静默授权用户无感知不需要用户手动点击同意。如果是敏感操作才需要 snsapi_userinfo。做支付建议一律用 snsapi_base不要为了提高“用户画像完整度”去申请用户信息授权那是另一套审核路径容易卡。这里有个极其典型的问题redirect_uri 必须事先在公众号后台配置为“网页授权域名”的完全匹配地址。比如配置了https://api.yourdomain.com/pay那 redirect_uri 就只能是这个地址或其子路径。如果前端跳转时把参数加在域名后面拼成了另一个地址微信公众号会直接报“redirect_uri参数错误”。4.3 调起支付的两种姿势wx.chooseWXPay 与 WeixinJSBridge微信浏览器内调起支付目前主流有两种方式。第一种是通过微信JSSDK。需要先引入 JSSDK 脚本然后配置wx.config签名用的 jsapi_ticket 由后端通过接口获取再调wx.chooseWXPaywx.chooseWXPay({ timestamp: res.data.timeStamp, nonceStr: res.data.nonceStr, package: res.data.package, signType: res.data.signType, paySign: res.data.paySign, success: function (result) { // 用户完成支付 } });这里的参数和小程序的 wx.requestPayment 几乎一样实际上微信JSAPI支付的下单返回参数就是同一套区别只是前端环境不同。第二种是直接用内置的 WeixinJSBridge不需要引入 JSSDK。这里有个细节老版本代码一般写WeixinJSBridge.invoke(getBrandWCPayRequest, { appId: res.data.appId, timeStamp: res.data.timeStamp, nonceStr: res.data.nonceStr, package: res.data.package, signType: res.data.signType, paySign: res.data.paySign }, function (res) { if (res.err_msg get_brand_wcpay_request:ok) { // 支付完成 } });注意 WeixinJSBridge 版本里多了一个appId字段而 JSSDK 的 chooseWXPay 不需要 appId。实际开发中我更推荐用 JSSDK因为它是官方文档主推、前后兼容性好遇到 bridgeReady 处理起来也比较稳定。4.4 关于“伪造微信浏览器UA”的风险说明很多外部H5页面被要求在微信内打开有人会想我改一下浏览器标识UA伪装成微信是不是就能直接调起支付这里必须泼一盆冷水。微信支付的安全性依赖微信客户端内的JSAPI核心能力UA识别只是前端展示层的判断真正调起支付还需要微信客户端提供的 native 能力通道。光改UA后端拿不到 openidWeixinJSBridge 接口也不存在所以不可能绕过支付限制。换个角度说如果你做的是“外部浏览器唤起微信支付”那就不需要伪造UA应该老老实实走微信H5支付接口。UA伪装这种思路在支付链路里注定是死路一条别再浪费时间研究。5. 外部浏览器唤起微信微信H5支付如果用户不在微信客户端里还想用微信支付唯一正路就是微信H5支付产品名就是“微信H5支付”。这个场景在电商、体验类H5活动、App内WebView里很常见。5.1 什么时候必须用H5支付判断条件很直接用户是在微信外浏览器打开的页面又选择“微信支付”此时必须用H5支付。如果用户已经在微信内这套方案反而用不了因为微信会拦截。很多同学会遇到一个迷惑场景用户在百度搜索进入一个H5商城点击微信支付后页面跳到一个看起来像微信官方的确认支付页然后自动唤起微信。这就是微信H5支付的完整表现。它通过后端下单返回一个h5_url前端302跳转到这个地址微信客户端识别到该URL后自动拉起收银台。5.2 H5支付下单与跳转H5下单接口是POST https://api.mch.weixin.qq.com/v3/pay/transactions/h5请求体比JSAPI多一个scene_info{ appid: wx1234567890abcdef, mchid: 1900000001, description: H5订单测试, out_trade_no: 20250115123200001, notify_url: https://api.yourdomain.com/pay/notify, amount: { total: 100, currency: CNY }, scene_info: { payer_client_ip: 116.25.46.188, h5_info: { type: Wap, wap_url: https://h5.yourdomain.com, wap_name: 你的商城名称 } } }payer_client_ip是用户的真实IPv4地址很多项目直接填服务端IP或空值这个字段在风控上非常重要建议从前端请求头里透传。wap_name会展示在微信支付确认页里需要与你的商户主体经营范围保持一致否则可能被风控拦截。下单成功返回h5_url后端直接重定向header(Location: . $h5Url, true, 302);如果是前后端分离架构也可以直接把h5_url返回给前端由前端window.location.href跳转。注意这个地址不要做短链、不要套一层自己的跳转参数微信会校验来源和时效性。5.3 H5支付的限制与合规红线H5支付有一些硬性限制第一次接入很容易被坑必须配置 H5支付域名。商户平台里要添加发起支付的页面域名跳转的h5_url与配置域名要能对应上。微信内禁止使用。官方文档明确写了H5支付只能在微信外部浏览器使用微信内必须走JSAPI。所以业务方要做环境判断微信内显示“请使用微信内置浏览器打开后支付”否则用户看到的会是一个无法闭环的报错页。有风控意识。H5支付在非微信环境下用户身份无法通过openid直接识别微信的风控会比较严格。同一设备频繁更换订单、团伙批量注册下单、用代理IP混淆位置都可能被判定为可疑交易而被拦截。支付网关如果同时接了微信JSAPI和微信H5支付我建议回调地址用同一个因为两者回调的报文字段结构完全一致后端处理逻辑不需要拆分。6. 跨端项目uniapp的支付差异现在很多项目是uniapp做的一套代码编小程序、App、H5。支付这个模块到了跨端场景下特别注意前端API统一了但底层参数并不统一。6.1 小程序端与App端支付参数的差异uniapp 里调起支付用的是uni.requestPayment但 provider 和参数结构在小程序端和App端完全不同。小程序端微信小程序运行环境uni.requestPayment({ provider: wxpay, timeStamp: 1736900000, nonceStr: xxx, package: prepay_idxxx, signType: RSA, paySign: xxx, success: function (res) {} });App端打包成 Android/iOS 应用后uni.requestPayment({ provider: wxpay, orderInfo: orderInfoStr, success: function (res) {} });App端这里不是传 timeStamp、paySign 这些键值对而是传一个由后端拼接好的orderInfo字符串。这个字符串在Android端是微信SDK要求的 orderInfo 格式iOS端同样需要用 SDK 能识别的结构不能拿小程序端的参数硬套。所以我给团队定的规矩是支付参数组装绝不做在前端而是由后端根据客户端类型分别返回对应字段。小程序端返回小程序参数App端返回App的orderInfoH5端返回跳转URL或者JSSDK参数。前端不重复造轮子只负责判断当前运行环境、然后取对应参数调起。6.2 几个容易踩的跨端支付坑第一个坑是 App 端顺序。App 调起微信支付前需要先确认微信是否安装以及是否已经在开放平台申请了移动应用并拿到了App的 appid。很多人只在小程序后台配置了AppID忘了开放平台注册移动应用结果App端怎么调都提示“微信未安装或版本过低”。第二个坑是调用时机。站在用户点击支付按钮到支付成功之间的这段时间请求可能非常频繁。跨端项目里H5和App场景很容易出现用户返回页面后再次点击支付导致重复下单。我的方案是下单前加一个幂等键前端每次进支付页生成一个 transaction_id后端对同一个 transaction_id 只允许创建一笔未支付订单重复请求直接返回老订单从根上杜绝重复扣款风险。第三个坑是回调地址不能区分端。App支付、小程序支付、H5支付的回调报文结构一致后端收到回调后不要试图通过报文里的某个字段判断“这笔单来自哪个端”而是应该用自己数据库里的订单记录判断业务状态。订单表里存订单来源字段回调更新状态时只处理这一条记录。7. 高频报错与线上问题排查支付上线后真正消耗精力的不是写代码而是各种莫名其妙的线上报错。我把这些年遇到的、以及身边同行反馈过的高频问题整理成了一个排查手册。7.1 用户态签名signature错误这个问题在小程序和公众号H5支付里非常高频报错通常来自前端调起收银台时的paySign校验不过。排查思路分四步检查待签名串顺序。必须是appId\n timeStamp\n nonceStr\n package\npackage 的值一定带prepay_id前缀。检查签名算法。v3接口下前端 paySign 用 RSA-SHA256对的但很多老项目v2还在用 MD5对照报错信息里的 signType 去查。如果后端返回的是signType: MD5前端却按 RSA 验签必然失败。检查换行符。拼接签名串时确认每个字段后面都有真实的换行符不是反斜杠n字符串。检查拿到的 prepay_id 对应下单接口版本。用v3接口下单返回的 prepay_id 在调起时却配了v2参数签名体系就完全错位了。7.2 iOS小程序网络请求失败6001“6001”在小程序网络报错里几乎成了iOS专有名场面。表现是同一份代码安卓正常iOS真机偶发请求失败错误码时不时是6001。这个真不一定是支付问题而是小程序网络请求底层的问题。常见诱因三个后端HTTPS证书链不完整iOS的NSURLSession要求证书链必须完整闭合缺失中间证书就握手失败。服务器只支持 HTTP/1.1 不支持部分 TLS 版本iOS在弱网或 IPv6 环境下协商失败。请求并发过高时小程序端内存被撑爆复用到支付流程时表现成接口偶发失败。排查路径开发者工具一般复现不了必须 iOS 真机打开调试模式配合“vConsole 看 request 返回的状态码和错误消息”反复切换飞行模式触发弱网再定位是 TLS 还是并发问题。我最后常用的解决手段是整体用wx.request封装统一拦截器重试逻辑里区分“网络不可达”和“业务失败”6001统一做一次请求级重试能挡住大半偶发故障。7.3 苹果虚拟支付与IAP退款在小程序里卖会员、卖课程、卖虚拟道具属于虚拟支付范畴。苹果的规则很明确iOS端虚拟商品必须通过 IAP苹果内购走微信小程序里用微信支付卖虚拟商品属于违规轻则审核被打回重则整个虚拟支付能力被限制。所以如果项目涉及虚拟商品支付产品设计要在前端提前分端分流iOS端走 IAP安卓和微信H5端走微信支付。这里还有个很烦的问题用户走 IAP 购买后申请退款苹果会通过App Store Server API推送退款通知服务端必须监听退款事件并主动回收用户已发放的虚拟权益。很多第一次做虚拟商品的同学忘了这一步结果用户白白退款还拿着VIP这就是纯资损了。7.4 年审、导航栏高度、请求封装等运营开发细节做微信生态支付旁边总有一堆非支付但影响体验的“邻居问题”。这里顺手记录几个高频关键词对应的方案。微信小程序年审这块主体认证到期后小程序功能不受影响但部分类目和接口权限可能被收紧。支付本身不依赖年审但如果支付页面涉及需要特定类目的业务功能年审过期可能导致审核类目失效。建议把年审时间记在运营日历里提前一个月准备续期资料。顶部导航栏高度的话题在小程序里一直有热度尤其做自定义导航栏时。不同机型的状态栏高度不一样官方提供了wx.getWindowInfo()或wx.getMenuButtonBoundingClientRect()拿胶囊位置。最稳的做法是拿到胶囊的顶部和底部坐标然后用它反推导航栏的安全高度不要硬编码数值否则iPhone和安卓横竖屏一换就裂开。请求封装这个点把uni.request或wx.request封装成统一拦截器是支付项目的基本功。我一般会在拦截器里做四件事统一拼接token、统一处理服务端错误码、对支付类接口做特殊透传、超时和网络错误自动重试。这样支付流程的代码会变得干净很多排查问题时也能一眼看到请求在哪一步丢了。最后再分享一个我自己的习惯这几年做支付项目我最深的一个体会是支付本身并不难难的永远是交易闭环和异常处理。所以我从第二个支付项目开始就定了一条铁律——所有的交易状态流转以数据库为准前端展示永远只作为辅助信息。用户看到的“支付成功”弹窗只是提示后端回调落库后才是真正的成功。我甚至在回调里还会再做一次“主动查单”回调成功后立即调用微信支付查单接口确认最终状态双重校验后才更新订单。这套做法帮我挡过不少线上资损。如果你正在负责支付模块我建议你也把“下单幂等、回调幂等、金额二次校验”这三道防线提前做成基础设施而不是等出了问题再补。支付是直接碰钱的地方每一次线上失误代价都不小。希望这篇折腾出来的经验能让你少踩几个坑。