微信公众号 / 小程序 / 微信支付 开发全流程教程
版本:2026-11 整理版 适用场景:LikeShop 类商城系统(服务号 H5 + 小程序 + 微信支付),ThinKPHP / Nginx / 阿里云 ESA / 1Panel 部署环境 用途:术语速查 + 数据流理解 + 配置落位 + 报错排查。开发时对照使用。
目录
一、先分清五大平台
很多混乱来自"后台入口搞不清"。微信生态实际是 5 个互相独立的平台,各有账号体系、各有 AppID/密钥、互不替代。
| # | 平台 | 域名 | 干什么 | 你在这里配什么 |
|---|---|---|---|---|
| 1 | 微信公众平台(公众号) | mp.weixin.qq.com | 服务号/订阅号后台 | 网页授权域名、JS 安全域名、消息推送、AppSecret、IP 白名单 |
| 2 | 微信公众平台(小程序) | mp.weixin.qq.com | 小程序后台(独立账号) | request/upload/download/socket 域名、业务域名、订阅消息 |
| 3 | 微信开放平台 | open.weixin.qq.com | 跨应用身份打通 | 网站应用扫码登录、APP 登录、绑定公众号+小程序拿 UnionID |
| 4 | 微信支付商户平台 | pay.weixin.qq.com | 收款方后台 | 商户号、APIv3 密钥、支付证书、回调地址、交易/退款/对账 |
| 5 | 微信开发者中心 | developers.weixin.qq.com | 文档 + 监控 + 开发工具 | 只查资料、看接口日志,不做业务配置 |
一句话记忆口诀
mp = 账号自家后台(公众号、小程序分开登录,AppID 各自独立)
open = 打通用户身份(UnionID、网站/APP 登录)
pay = 收钱的地方(商户号、密钥、证书、回调)
developers = 查文档排错
最容易踩的三个入口误区
❌ 去 open.weixin.qq.com 找"网页授权回调域名""消息推送 URL" —— 这里没有。
❌ 以为公众号和小程序用户天然互通 —— 不互通,必须开放平台绑定才能拿 UnionID。
❌ 以为 pay 商户平台能改公众号配置 —— 完全独立,商户号和公众号 AppID 是两套东西(只是可以互相关联绑定)。
二、核心术语总表
| 术语 | 归属 | 含义 | 有效期/限制 |
|---|---|---|---|
| AppID | mp / open | 应用唯一标识(公众号、小程序、开放平台各自一个) | 永久 |
| AppSecret | mp / open | 应用密钥,换取 access_token 用 | 永久,务必保密、只存后端 |
| openid | 公众号 / 小程序 | 用户在单个应用内的唯一 ID | 永久,但换应用就变 |
| unionid | open | 同一主体下,用户跨公众号/小程序/APP 唯一不变 ID | 永久,需绑定开放平台 |
| code | 各处 | 临时授权票据 | 5 分钟、一次性 |
| access_token(基础) | 公众号 mp | 调公众号后台接口的全局凭证 | 2 小时,需缓存 + IP 白名单 |
| access_token(网页授权) | 公众号 OAuth | 拉取用户信息专用 | 2 小时,与基础 token 不通用 |
| session_key | 小程序 | 解密手机号等敏感数据的会话密钥 | 随登录刷新 |
| jsapi_ticket | 公众号 mp | JS-SDK 签名票据 | 2 小时,需缓存 |
| prepay_id | pay | 统一下单返回的预支付订单号 | 2 小时 |
| mch_id | pay | 商户号 | 永久 |
| signature | 各处 | 请求签名,防伪造 | 单次 |
| echostr | 公众号 mp | 消息推送验证阶段的回显字符串 | 单次 |
三、公众号(服务号)体系
服务号才具备:网页授权、JS-SDK、消息推送、微信支付、模板/订阅消息。订阅号基本没有网页授权能力。
3.1 网页授权 OAuth2.0(拿 openid,实现微信登录)
关键配置
公众号后台 → 设置与开发 → 公众号设置 → 功能设置 → 网页授权域名
只填裸域名:
xnb.me不带
https://、不带路径、不带端口、不支持泛域名*.xnb.me需要上传微信提供的
MP_verify_xxx.txt校验文件到网站根目录
关键参数
| 参数 | 说明 |
|---|---|
appid | 公众号 AppID |
redirect_uri | 授权后跳回的地址,必须 URL 编码,域名必须在白名单内 |
response_type | 固定 code |
scope | snsapi_base(静默,只拿 openid)/ snsapi_userinfo(弹窗,可拿昵称头像) |
state | 自定义参数(防 CSRF、带业务标识),回调会原样带回 |
code | 回调带回的票据,换 token 用 |
#wechat_redirect | 链接末尾必须带上,否则部分场景不跳转 |
数据流(逐步)
1. 用户在微信内置浏览器打开:https://xnb.me/login
2. 后端拼接授权链接(返回 302 给浏览器):
https://open.weixin.qq.com/connect/oauth2/authorize
?appid=wx123456
&redirect_uri=https%3A%2F%2Fxnb.me%2Fapi%2Fwechat%2Fcallback
&response_type=code
&scope=snsapi_base
&state=abc123
#wechat_redirect
3. 浏览器跳到微信服务器 open.weixin.qq.com
4. 微信校验阶段(★ 关键):
- 解析 redirect_uri → 提取域名 xnb.me
- 对比后台【网页授权域名】白名单
- 不一致 → 直接报 10003,页面显示"redirect_uri 域名与后台配置不一致"
- 此阶段微信还没有访问你的服务器,不是网络问题!
5. 校验通过:
- snsapi_base:不弹窗,直接 302 回 redirect_uri?code=xxx&state=abc123
- snsapi_userinfo:弹授权框 → 用户同意 → 302 回 redirect_uri?code=xxx&state=abc123
6. 后端收到 code,服务器侧(不是浏览器)请求:
GET https://api.weixin.qq.com/sns/oauth2/access_token
?appid=xx&secret=xx&code=xx&grant_type=authorization_code
返回:{ access_token, expires_in, refresh_token, openid, scope, unionid? }
7. 若 scope=snsapi_userinfo,再请求:
GET https://api.weixin.qq.com/sns/userinfo?access_token=xx&openid=xx&lang=zh_CN
8. 后端用 openid / unionid 建立商城会员会话
常见坑
redirect_uri里协议必须是https,ESA 回源协议错 → 后端拼出http://→ 10003回调地址末尾斜杠、大小写、
www有无,微信是完整字符串比对code 只能用一次,刷新页面就失效,必须重新走授权
3.2 JS-SDK(调用微信原生能力)
关键配置
公众号后台 → 设置与开发 → 公众号设置 → 功能设置 → JS 接口安全域名
与网页授权域名是两条独立配置,域名相同也要分别填两次
同样需要
MP_verify_xxx.txt校验
能力清单
| 接口 | 用途 |
|---|---|
wx.chooseImage / wx.chooseMedia | 拍照、选图 |
wx.getLocation / wx.openLocation | 定位、看地图 |
wx.scanQRCode | 扫一扫 |
wx.updateAppMessageShareData | 分享给好友 |
wx.updateTimelineShareData | 分享到朋友圈 |
wx.chooseWXPay | 拉起 JSAPI 支付 |
wx.startRecord | 录音 |
数据流
1. H5 页面加载完成,前端请求后端 /api/jssdk/config?url=当前页面url(不含#后内容)
2. 后端流程:
a. 取缓存的基础 access_token(https://api.weixin.qq.com/cgi-bin/token)
b. 用它换 jsapi_ticket(https://api.weixin.qq.com/cgi-bin/ticket/getticket?type=jsapi)
→ ticket 有效期 2 小时,必须缓存,全站共用
c. 拼签名串:
jsapi_ticket=xxx&noncestr=随机串×tamp=时间戳&url=当前页面完整url
d. sha1(签名串) → signature
3. 后端返回 { appId, timestamp, nonceStr, signature }
4. 前端执行:
wx.config({ debug:false, appId, timestamp, nonceStr, signature,
jsApiList:['chooseImage','updateAppMessageShareData',...] })
5. wx.ready 后即可调用各 wx.xxx 接口
6. wx.error 里能看到具体失败原因
常见坑
invalid signature:url 用了 SPA 路由后的地址、或 url 编码方式不对、或缓存了旧 ticketurl必须是当前页面完整地址(不含 #hash 部分),前端传给后端时要做 encodeURIComponent域名不在 JS 安全域名里 → config 直接失败
iOS 与 Android 对 url 的处理有差异,前端应强制传
location.href.split('#')[0]
3.3 消息推送(接收用户消息与事件)
关键配置
公众号后台 → 设置与开发 → 基本配置 → 服务器配置
| 字段 | 说明 |
|---|---|
| URL | 你的后端接口,如 https://www.xnb.me/api/wechat/server |
| Token | 自定义字符串,用于签名 |
| EncodingAESKey | 加密密钥(43 位) |
| 消息加解密方式 | 明文 / 兼容 / 安全(推荐) |
数据流(验证 + 收消息)
【验证阶段,只在保存配置时发生一次】
1. 点"提交",微信服务器向你填的 URL 发 GET 请求:
/api/wechat/server?signature=xxx×tamp=xxx&nonce=xxx&echostr=abc
2. 后端算签名:sha1(sort([token, timestamp, nonce]).join(''))
与 signature 比对
3. 一致 → 原样输出 echostr 字符串,HTTP 200
❗ 微信服务器不跟随 301/302!
如果该 URL 被 Nginx/ESA 重定向,验证直接失败
【收消息阶段,持续发生】
4. 用户发消息 / 关注 / 扫码 / 点菜单 / 支付完成事件
5. 微信服务器 POST 到你的 URL(XML 或 JSON,看配置)
6. 后端验签 → 解析消息体 → 处理业务(自动回复、记 openid、发券)
7. 5 秒内返回响应 XML;超时微信会重试(共 3 次,容易重复处理)
常见坑
推送 URL 允许被 301 跳转 → 必失败(你之前踩过:填 www 正常、填裸域失败,就是这个原因)
端口只支持 80/443,不支持自定义端口
明文模式最容易调试,但生产建议安全模式
微信重试机制必须有幂等处理,否则重复发券/重复加积分
3.4 公众号基础 access_token
接口:
GET https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=&secret=有效期 7200 秒
必须后台缓存(Redis / 文件),全站共用一份
需要 IP 白名单:mp 后台 → 基本配置 → IP 白名单(填你服务器出口 IP)
与网页授权 access_token 完全独立、不可混用
频繁刷新会导致旧 token 失效,建议提前 5 分钟刷新
3.5 模板消息 / 订阅通知
服务号:模板消息(用户关注即可发,2020 年后受限较多)
统一趋势:改用订阅通知(用户需主动点"允许")
用途:订单支付成功提醒、发货提醒、预约提醒
依赖基础 access_token
四、小程序体系
小程序没有网页授权 OAuth,登录是一套独立体系。
4.1 小程序登录(wx.login)
数据流
1. 前端 wx.login() → 拿到 code(5 分钟有效、一次性)
2. 前端把 code 传给后端
3. 后端请求:
GET https://api.weixin.qq.com/sns/jscode2session
?appid=xx&secret=xx&js_code=xx&grant_type=authorization_code
返回:{ openid, session_key, unionid? }
4. 后端生成自己的登录态(token/session),返回前端
5. 前端后续请求带自己的 token(★ 不要直接把 session_key 给前端保存太久)
与公众号 OAuth 的区别
| 公众号 OAuth | 小程序 wx.login | |
|---|---|---|
| 触发 | 用户点开 H5 | 小程序启动调用 |
| code 接口 | /sns/oauth2/access_token | /sns/jscode2session |
| 返回 | access_token + openid | openid + session_key |
| 是否会弹窗 | snsapi_userinfo 会 | 不会 |
4.2 小程序四类域名(极易混淆)
小程序后台 → 开发 → 开发管理 → 开发设置 → 服务器域名
| 类型 | 作用 | 典型报错 |
|---|---|---|
| request 合法域名 | 前端 wx.request 调后端接口(查商品、下单) | request:fail url not in domain list |
| uploadFile 合法域名 | wx.uploadFile 上传图片/文件 | 同上 |
| downloadFile 合法域名 | wx.downloadFile 下载 | 同上 |
| socket 合法域名 | WebSocket 长连接 | 同上 |
要求:必须 HTTPS、必须备案、不能带端口、不能是 IP、每月修改次数有限
4.3 业务域名(web-view 专用)
小程序后台 → 开发 → 开发管理 → 开发设置 → 业务域名
作用:
<web-view src="https://xnb.me/xxx">内嵌 H5 页面,该域名必须在业务域名列表需要把微信给的校验文件放到该域名根目录
报错:页面提示"不支持打开该域名"
一句话区分
request 域名 = 小程序自己的 JS 调接口
业务域名 = web-view 里加载的外部网页
你 LikeShop 小程序里用 web-view 打开 H5 商城 →
xnb.me必须加到业务域名;同时小程序自己的接口调用走 request 域名。
4.4 小程序订阅消息
替代旧的模板消息
用户必须主动点击授权(一次订阅一次推送 / 长期订阅)
后端接口:
POST https://api.weixin.qq.com/cgi-bin/message/subscribe/send需要小程序 access_token(
/cgi-bin/token,与公众号的是不同的)
4.5 获取手机号
前端
<button open-type="getPhoneNumber">→ 拿到加密数据 + code新版:直接用 code 调
POST https://api.weixin.qq.com/wxa/business/getuserphonenumber?access_token=xx属于付费能力(每次调用计费,按量收费)
五、微信开放平台 / UnionID 体系
5.1 为什么需要
默认情况下:
用户在你的服务号里 openid =
oA_xxxxx同一用户在小程序里 openid =
oB_yyyyy
两个 ID 完全不相干 → 商城会认成两个会员 → 账号不互通、积分不共享、订单分裂。
把公众号 + 小程序绑定到同一个开放平台账号下,两者的返回里都会带上同一个 unionid,用它做会员主键即可打通。
5.2 绑定前置条件
注册开放平台账号(open.weixin.qq.com),完成开发者资质认证(300 元/年)
公众号、小程序、APP、网站应用主体必须一致(同一营业执照)
在开放平台 → 管理中心 → 公众账号 / 小程序 里逐个绑定(需管理员扫码确认)
5.3 UnionID 获取路径
| 场景 | 是否返回 unionid |
|---|---|
| 公众号 OAuth(snsapi_base / userinfo) | 绑定后返回 |
| 小程序 jscode2session | 绑定后返回 |
| 未绑定开放平台 | 不返回 |
5.4 数据流
用户A 在服务号 H5 登录 → openid_A + unionid_U
用户A 在小程序登录 → openid_B + unionid_U
↓
LikeShop 会员表:以 unionid_U 作为唯一键
↓
两种入口登录 → 落到同一个会员账户(积分、订单、优惠券共享)
5.5 开放平台另外两个用途
网站应用:PC 官网"微信扫码登录"(
https://open.weixin.qq.com/connect/qrconnect)移动应用:APP 微信登录、微信分享(需应用签名、包名报备)
注意:开放平台的 AppID/AppSecret 和公众号、小程序的互不通用。
六、微信支付体系(重点)
微信支付是完全独立的第 4 个平台(pay.weixin.qq.com),跟公众号/小程序只是"关联"关系。
6.1 平台与账号关系
| 概念 | 说明 |
|---|---|
| 商户号 mch_id | 收款主体,可在 pay.weixin.qq.com 申请,需营业执照 |
| AppID 关联 | 商户号需在【产品中心 → AppID 账号管理】里关联你的公众号/小程序 AppID,否则下单报错 |
| APIv2 密钥 | 32 位,MD5/HMAC-SHA256 签名用(老接口) |
| APIv3 密钥 | 32 位,AES-256-GCM 加解密 + 新版签名(推荐全部用 V3) |
| 商户 API 证书 | apiclient_cert.pem + apiclient_key.pem,V3 签名必需 |
| 平台证书 / 微信支付公钥 | 用于验签回调与响应(2023 后新商户改用"微信支付公钥") |
| 支付回调 URL | 微信服务器异步 POST 支付结果,不能是 301 跳转地址 |
| 退款回调 URL | 退款结果异步通知 |
6.2 支付产品类型速查(选错就白干)
| 产品 | 使用场景 | 调起方式 | 必备条件 |
|---|---|---|---|
| JSAPI 支付 | 微信内 H5(公众号) | wx.chooseWXPay | 公众号 AppID + JS 安全域名 + 商户号关联 + 用户 openid |
| 小程序支付 | 小程序内 | wx.requestPayment | 小程序 AppID + 用户 openid(小程序 openid) |
| H5 支付(MWEB) | 微信外的浏览器(手机浏览器、App 内) | 跳转中间页 | 单独开通 MWEB,需场景域名 |
| Native 支付 | PC 网站显示二维码 | 扫码 | 开通 Native |
| APP 支付 | 原生 App | SDK 调起 | 开放平台移动应用 + 应用签名 |
| 付款码支付 | 线下收银扫用户付款码 | 商户扫 | 开通刷卡支付 |
| 刷脸支付 | 线下设备 | 设备 SDK | 专用设备 |
⚠️ 最常见的错:在微信内置浏览器里用 H5(MWEB) 支付 —— 微信内不支持 MWEB,必须用 JSAPI。反之在外部浏览器用 JSAPI 也不行。
6.3 JSAPI 支付完整数据流(公众号 H5,你最常用)
【前置】
- 商户号已关联公众号 AppID
- 已配置支付授权目录(若用旧版 V2;V3 不再强依赖,但建议配)
- 公众号已配置 JS 安全域名
- 用户已通过 OAuth 拿到 openid(★ 必须是该公众号 AppID 下的 openid)
【下单】
1. 前端点"立即支付" → 请求后端 /api/pay/create,带订单号、金额、openid
2. 后端组装请求,调 V3 统一下单:
POST https://api.mch.weixin.qq.com/v3/pay/transactions/jsapi
Header: Authorization: WECHATPAY2-SHA256-RSA2048 mchid="..",nonce_str="..",
signature="..",timestamp="..",serial_no=".."
Body:
{
"appid": "公众号AppID",
"mchid": "商户号",
"description": "商品描述",
"out_trade_no": "商城订单号(唯一)",
"notify_url": "https://xnb.me/api/pay/notify", ← 支付回调
"amount": { "total": 100, "currency": "CNY" }, ← 单位:分
"payer": { "openid": "用户openid" }
}
签名算法:SHA256-RSA2048,用商户私钥 apiclient_key.pem 签
待签串:HTTP方法 URL路径 时间戳 随机串 请求体 (每行末尾 )
3. 微信返回:{ "prepay_id": "wx3017xxxxxxxx" }
【二次签名(给前端调起用)】
4. 后端用 prepay_id 生成调起参数并签名:
{
"appId": "公众号AppID",
"timeStamp": "时间戳字符串",
"nonceStr": "随机串",
"package": "prepay_id=wx3017xxxxxxxx",
"signType": "RSA",
"paySign": "用商户私钥对 appId timeStamp nonceStr package 签名"
}
5. 前端:
wx.chooseWXPay({ timeStamp, nonceStr, package, signType:'RSA', paySign,
success(){ 跳支付成功页 },
cancel(){ 用户取消 },
fail(){ 报错 }
})
【支付结果】
6. 用户输密码付款成功
7. 微信服务器异步 POST 到你 notify_url(★ 不跟随 301!)
Body(V3 是 JSON,且加密):
{
"id":"EV-xxx", "event_type":"TRANSACTION.SUCCESS",
"resource": { "algorithm":"AEAD_AES_256_GCM",
"ciphertext":"...", "nonce":"...", "associated_data":"..." }
}
8. 后端处理:
a. 验签(用微信支付公钥/平台证书验 Wechatpay-Signature 头)
b. 用 APIv3 密钥 AES-256-GCM 解密 resource.ciphertext → 明文交易对象
c. 校验 out_trade_no、amount.total、trade_state=SUCCESS
d. 幂等处理:同一笔订单重复通知只处理一次
e. 更新订单状态、发货/发券/加积分
f. 返回 HTTP 200 + {"code":"SUCCESS"}(或空 200/204)
9. 前端 success 回调只是"用户端感知",**真正以回调通知为准**!
6.4 小程序支付数据流
与 JSAPI 几乎一致,差异只有三处:
| 环节 | JSAPI(公众号) | 小程序 |
|---|---|---|
| appid 传值 | 公众号 AppID | 小程序 AppID |
| payer.openid | 公众号 openid | 小程序 openid |
| 前端调起 | wx.chooseWXPay | wx.requestPayment |
wx.requestPayment 参数完全一致(timeStamp / nonceStr / package / signType / paySign)。
6.5 H5(MWEB)支付数据流
1. 后端下单(V3 H5 接口):
POST https://api.mch.weixin.qq.com/v3/pay/transactions/h5
Body 增加:
"scene_info": {
"payer_client_ip": "用户真实IP",
"h5_info": { "type": "Wap" }
}
2. 返回 { "h5_url": "https://wx.tenpay.com/cgi-bin/mmpayweb-bin/checkmweb?prepay_id=..." }
3. 前端 location.href = h5_url
4. 用户在微信中间页付款
5. 回调同 JSAPI
关键要求
必须传用户真实公网 IP(在 ESA/CDN 后面必须从
X-Forwarded-For里取第一个)必须单独开通 MWEB 产品
必须在商户平台配置H5 支付域名(场景域名)
微信内置浏览器打开会失败 → 要判断 UA,微信内改走 JSAPI
6.6 回调验签(V3)关键细节
请求头:
Wechatpay-Timestamp: 时间戳
Wechatpay-Nonce: 随机串
Wechatpay-Signature: 签名(base64)
Wechatpay-Serial: 平台证书序列号 或 微信支付公钥ID
验签串:
timestamp nonce body (每行末尾 ,最后一行也要 )
用微信支付公钥(或对应平台证书公钥)做 SHA256-RSA 验签
★ 必须校验 timestamp 与当前时间差 < 5 分钟,防重放
6.7 支付回调的 Nginx / ESA 必配
因为微信服务器不跟随 301/302,回调路径必须直连:
# 支付回调、微信消息推送,禁止域名跳转,直接透传
location ~ ^/api/(pay/notify|refund/notify|wechat/server) {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_read_timeout 10s;
}同时在 ESA 上给这三个路径加豁免重定向规则,否则 ESA 直接返回 301。
6.8 退款流程
1. 后端调:
POST https://api.mch.weixin.qq.com/v3/refund/domestic/refunds
Body:
{
"out_trade_no": "原订单号", // 或 transaction_id
"out_refund_no": "退款单号(唯一)",
"reason": "用户申请退款",
"notify_url": "https://xnb.me/api/refund/notify",
"amount": { "refund": 100, "total": 100, "currency": "CNY" }
}
2. 同步返回 status=PENDING(处理中)
3. 异步通知:REFUND.SUCCESS / REFUND.ABNORMAL / REFUND.CLOSED
4. 收到 SUCCESS 后更新订单为已退款、回滚库存/积分6.9 订单查询 / 关闭
| 功能 | V3 接口 |
|---|---|
| 查单 | GET /v3/pay/transactions/out-trade-no/{out_trade_no}?mchid= |
| 关单 | POST /v3/pay/transactions/out-trade-no/{out_trade_no}/close |
| 对账单 | GET /v3/bill/tradebill?bill_date=&bill_type= → 返回下载链接 |
典型用途:前端 success 但回调丢了 → 后端主动查单兜底(生产必备)。
6.10 支付避坑清单
金额单位是「分」,1 元 = 100,不要传 1.00
out_trade_no必须唯一,重复下单要幂等notify_url必须 HTTPS 公网可访问、不能带参数、不能是 301回调必须验签 + 解密 + 校验金额,否则可被伪造
以回调为准,不以客户端 success 为准
回调要幂等,微信会重试最多 8 次(间隔递增)
必须做主动查单兜底,回调丢失时不至于掉单
ESA / CDN 后面取客户端 IP 要用
X-Forwarded-For第一段商户号必须关联 AppID,否则报
APPID_MCHID_NOT_MATCHV3 签名串最后一行必须带
,少一个换行就验签失败(超高频坑)平台证书 / 微信支付公钥要定期更新,缓存过期会验签失败
不要用 APIv2 的 MD5 签名去调 V3 接口
七、完整数据流总览
7.1 三层身份链路
【第一层:拿身份】
公众号 H5:OAuth → code → openid / unionid
小程序:wx.login → code → openid / unionid
【第二层:统一会员】
open.weixin.qq.com 绑定 → unionid 作为会员主键
LikeShop 会员表(unionid) → 一个用户一个账号
【第三层:交易】
会员下单 → 订单号 out_trade_no
→ 支付下单(appid + mchid + openid)→ prepay_id
→ 前端调起 → 用户付款
→ 微信异步回调 notify_url → 验签解密 → 更新订单
→ (兜底)主动查单7.2 谁主动发起请求?——决定能不能 301
| 请求方 | 场景 | 是否跟随 301/302 |
|---|---|---|
| 用户浏览器 | OAuth 授权跳转、H5 支付跳转 | ✅ 会跟随 |
| 微信服务器 | 消息推送验证、消息推送、支付回调、退款回调 | ❌ 不跟随,遇跳转即失败 |
这是你之前"填 www 正常、填裸域失败"以及所有回调类故障的总根源。
7.3 ESA / CDN 代理下的头透传(必配)
用户 → ESA(HTTPS) → 源站 Nginx(HTTP回源) → PHP 必须保证: 1. ESA 回源协议 = follow(跟随客户端) 2. ESA 回源 Host = 客户端请求域名 3. ESA 转换规则加请求头: X-Forwarded-Proto = client scheme X-Forwarded-Host = client host X-Forwarded-For = client ip 4. Nginx: proxy_set_header Host $host; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-For $remote_addr; 5. ThinkPHP config/app.php: 'proxy_server' => ['ESA回源IP段']
少了第 5 步,TP6 会直接丢弃 X-Forwarded-Proto,后端仍认为是 http → 拼出 http 的 redirect_uri → 10003。这是最隐蔽的坑。
八、配置落位对照表
| 配置项 | 平台 | 菜单路径 |
|---|---|---|
| 网页授权域名 | 公众号 mp | 设置与开发 → 公众号设置 → 功能设置 → 网页授权域名 |
| JS 接口安全域名 | 公众号 mp | 设置与开发 → 公众号设置 → 功能设置 → JS 接口安全域名 |
| 消息推送 URL/Token/AESKey | 公众号 mp | 设置与开发 → 基本配置 → 服务器配置 |
| 公众号 IP 白名单 | 公众号 mp | 设置与开发 → 基本配置 → IP 白名单 |
| 公众号 AppSecret | 公众号 mp | 设置与开发 → 基本配置 → 开发者密码 |
| 小程序 request 等域名 | 小程序 mp | 开发 → 开发管理 → 开发设置 → 服务器域名 |
| 小程序业务域名 | 小程序 mp | 开发 → 开发管理 → 开发设置 → 业务域名 |
| 小程序 AppSecret | 小程序 mp | 开发 → 开发管理 → 开发设置 → 开发者 ID |
| UnionID 绑定 | open | 管理中心 → 公众账号 / 小程序 → 绑定 |
| 网站应用(扫码登录) | open | 管理中心 → 网站应用 → 创建 |
| 商户号 / APIv3 密钥 | pay | 账户中心 → API 安全 → APIv3 密钥 |
| 商户 API 证书 | pay | 账户中心 → API 安全 → API 证书 |
| AppID 关联商户号 | pay | 产品中心 → AppID 账号管理 |
| 支付回调 URL | 代码里传 | notify_url 参数(不在此后台配,旧版需配支付目录) |
| H5 支付场景域名 | pay | 产品中心 → H5 支付 → 场景域名 |
| 支付授权目录(V2 遗留) | pay | 产品中心 → 开发配置 |
九、LikeShop 对接标准流程
阶段一:账号准备
服务号(已认证)+ 小程序(已认证)+ 商户号 + 开放平台(已认证)
四者主体一致
商户号关联公众号 AppID 和小程序 AppID
阶段二:公众号配置(mp)
网页授权域名:
xnb.meJS 接口安全域名:
xnb.me上传
MP_verify_xxx.txt到网站根目录并可访问服务器配置:URL =
https://www.xnb.me/api/wechat/server,Token 记下,AESKey 记下,安全模式IP 白名单填服务器公网出口 IP
⚠️ 推送 URL 用
www更稳(若裸域有 301 跳转);或按第 6.7 节给该路径加豁免。
阶段三:小程序配置(mp)
request 合法域名:
https://xnb.meuploadFile / downloadFile 域名
业务域名:
xnb.me(web-view 用,需放校验文件)记录 AppID / AppSecret
阶段四:开放平台(open)
绑定服务号 + 小程序
确认 OAuth / jscode2session 返回里有 unionid
(可选)创建网站应用做 PC 扫码登录
阶段五:支付(pay)
下载 API 证书(apiclient_cert.pem / apiclient_key.pem)放服务器安全目录
设置 APIv3 密钥(32 位)
下载微信支付公钥(或平台证书)
商户号关联公众号 + 小程序 AppID
若需外部浏览器支付:开通 H5 支付并配置场景域名
回调地址:
https://xnb.me/api/pay/notify、https://xnb.me/api/refund/notify
阶段六:代码 / 服务器
Nginx 给
/api/pay/notify、/api/refund/notify、/api/wechat/server加豁免跳转ESA 给同样路径加豁免重定向规则
Nginx 透传 Host / X-Forwarded-Proto / X-Forwarded-For
ThinkPHP
proxy_server信任 ESA 回源 IP基础 access_token、jsapi_ticket 做 Redis 缓存
支付回调做验签 + 解密 + 幂等 + 金额校验
支付加主动查单兜底定时任务
阶段七:联调顺序(务必按此顺序)
1. OAuth 登录(拿 openid) ← 先解决 10003 2. JS-SDK 签名(wx.config 通过) 3. 消息推送验证(echostr 返回成功) 4. 小程序 wx.login(拿 openid) 5. UnionID 打通验证(两边 unionid 一致) 6. 下单 + JSAPI 支付(小额 0.01 元测试) 7. 支付回调接收 + 订单状态变更 8. 退款流程 9. 对账(下载昨日对账单核对)
十、错误码速查表
公众号 / 授权类
| 错误码/报错 | 原因 | 解决 |
|---|---|---|
| 10003 redirect_uri 域名与后台配置不一致 | redirect_uri 域名不在白名单 / 协议不对(http vs https) | 核对后台域名裸域名;修 ESA 回源协议 + 头透传 + TP proxy_server |
| 40001 | AppSecret 错误 / access_token 无效 | 重设 secret,清缓存重取 token |
| 40013 | AppID 无效 | 核对 AppID |
| 40029 | code 无效(已用过或过期) | 重新走授权,不要复用 code |
| 40125 | AppSecret 无效 | 商户/公众号后台重置 |
| 40164 | 调用 IP 不在白名单 | mp 后台加 IP |
| 45009 | 接口调用超限 | 加缓存,减少调用频率 |
| 48001 | 接口未授权(服务号未认证) | 完成认证 |
| 50002 | 用户受限(未关注/被封) | 提示用户关注 |
| invalid signature | JS-SDK 签名错误 | url 用 split('#')[0];ticket 缓存校验;注意 encodeURIComponent |
| config:invalid url domain | 域名不在 JS 安全域名 | 补齐后台配置 |
小程序类
| 报错 | 原因 |
|---|---|
request:fail url not in domain list | request 域名未配 / 未备案 / 带端口 |
不支持打开该域名 | web-view 域名未加业务域名 |
41004 | 小程序 AppSecret 缺失/错误 |
40165 | 请求的 openid 非本小程序 |
47001 | 数据格式错误(JSON 拼错) |
微信支付类
| 错误码 | 含义 | 处理 |
|---|---|---|
APPID_MCHID_NOT_MATCH | AppID 与商户号未关联 | pay 后台关联 |
PARAM_ERROR | 参数错误(金额单位/字段名) | 检查 total 单位是分 |
SIGN_ERROR / SIGNATURE_ERROR | 签名错误 | V3 签名串换行 、私钥路径、序列号 |
ORDERPAID | 订单已支付 | 幂等处理,直接返回成功 |
ORDER_CLOSED | 订单已关闭 | 重新下单 |
OUT_TRADE_NO_USED | 订单号重复使用 | 换新单号/幂等复用原单 |
NOT_ENOUGH | 余额不足 | 提示用户 |
PAYER_OPENID_NOT_MATCH | openid 与 appid 不匹配(公众号 openid 用在小程序) | 用对应 AppID 的 openid |
NO_AUTH | 无该接口权限 | 商户平台开通产品 |
FREQUENCY_LIMITED | 频率超限 | 降低请求频率 |
| 验签失败(回调) | 平台证书/公钥过期、串拼错 | 更新证书,检查串格式与 timestamp |
十一、避坑总纲
1. 跳转是万恶之源
微信服务器主动发起的请求一律不跟随 301/302:消息推送、支付回调、退款回调、授权验证 echostr
用户浏览器发起的跳转没问题:OAuth、H5 支付中间页
做法:给这些路径在 Nginx 和 ESA 双向加豁免,或干脆推送/回调统一用
www域名
2. 域名配置四条铁律
公众号的"网页授权域名"和"JS 安全域名"是两条独立配置,各填一次
都只填裸域名,不带协议、路径、端口、泛域名
都需要
MP_verify_xxx.txt校验文件在根目录可访问小程序的"业务域名"≠"request 域名"
3. 三种 token 不要混
基础 access_token(公众号后台接口)
网页授权 access_token(拉用户信息)
小程序 access_token(订阅消息等)
jsapi_ticket(JS-SDK 签名)
全部要缓存,全部 2 小时过期,全部不要每次请求现取。
4. code 特性
5 分钟有效、一次性、不可缓存、不可复用、不可前端保存
5. 支付五条命
金额单位是分
回调必须验签 + 解密 + 校验金额 + 幂等
以回调为准,前端 success 只是提示
必须有主动查单兜底
V3 签名串最后一行必须带
6. 代理环境(ESA/CDN)三件套
回源协议 follow
Host / X-Forwarded-Proto / X-Forwarded-For 透传
ThinkPHP
proxy_server信任代理 IP
缺一环,后端识别成 http,OAuth 10003、支付回调异常一起爆发。
7. openid 与 unionid
openid 只在单应用内有效
打通账号必须走开放平台 unionid
支付时 openid 必须与下单传的 AppID 属于同一应用
十二、附录:常用接口清单
公众号
| 用途 | 接口 |
|---|---|
| 获基础 token | GET https://api.weixin.qq.com/cgi-bin/token |
| 获 jsapi_ticket | GET https://api.weixin.qq.com/cgi-bin/ticket/getticket?type=jsapi |
| OAuth 换 token | GET https://api.weixin.qq.com/sns/oauth2/access_token |
| 刷新 OAuth token | GET https://api.weixin.qq.com/sns/oauth2/refresh_token |
| 拉用户信息 | GET https://api.weixin.qq.com/sns/userinfo |
| 校验 OAuth token | GET https://api.weixin.qq.com/sns/auth |
| 创建菜单 | POST https://api.weixin.qq.com/cgi-bin/menu/create |
| 模板消息 | POST https://api.weixin.qq.com/cgi-bin/message/template/send |
| 订阅通知 | POST https://api.weixin.qq.com/cgi-bin/message/subscribe/bizsend |
| 生成带参二维码 | POST https://api.weixin.qq.com/cgi-bin/qrcode/create |
小程序
| 用途 | 接口 |
|---|---|
| 登录换 openid | GET https://api.weixin.qq.com/sns/jscode2session |
| 获小程序 token | GET https://api.weixin.qq.com/cgi-bin/token |
| 订阅消息 | POST https://api.weixin.qq.com/cgi-bin/message/subscribe/send |
| 获取手机号 | POST https://api.weixin.qq.com/wxa/business/getuserphonenumber |
| 生成小程序码 | POST https://api.weixin.qq.com/wxa/getwxacodeunlimit |
| 内容安全检测 | POST https://api.weixin.qq.com/wxa/msg_sec_check |
微信支付 V3
| 用途 | 接口 |
|---|---|
| JSAPI/小程序下单 | POST https://api.mch.weixin.qq.com/v3/pay/transactions/jsapi |
| H5 下单 | POST https://api.mch.weixin.qq.com/v3/pay/transactions/h5 |
| Native 下单 | POST https://api.mch.weixin.qq.com/v3/pay/transactions/native |
| APP 下单 | POST https://api.mch.weixin.qq.com/v3/pay/transactions/app |
| 查单 | GET https://api.mch.weixin.qq.com/v3/pay/transactions/out-trade-no/{no}?mchid= |
| 关单 | POST https://api.mch.weixin.qq.com/v3/pay/transactions/out-trade-no/{no}/close |
| 申请退款 | POST https://api.mch.weixin.qq.com/v3/refund/domestic/refunds |
| 查询退款 | GET https://api.mch.weixin.qq.com/v3/refund/domestic/refunds/{out_refund_no} |
| 交易账单 | GET https://api.mch.weixin.qq.com/v3/bill/tradebill |
| 资金账单 | GET https://api.mch.weixin.qq.com/v3/bill/fundflowbill |
| 下载平台证书 | GET https://api.mch.weixin.qq.com/v3/certificates |
附:一页纸速记
平台:mp(账号配置) / open(身份打通) / pay(收钱) / developers(文档) 公众号三配置: 网页授权域名 → 为 OAuth 登录(拿 openid) JS 安全域名 → 为拍照/定位/分享/JSAPI 支付 消息推送 URL → 为收消息事件(禁 301) 小程序四域名 + 业务域名: request/upload/download/socket → 前端调接口 业务域名 → web-view 嵌 H5 身份:openid (单应用) / unionid (跨应用,需 open 绑定) 支付: 选对产品(微信内=JSAPI,小程序=小程序支付,外部浏览器=MWEB) 金额单位分;回调验签解密校额幂等;以回调为准;查单兜底 代理: ESA 回源 follow + 头透传 + TP proxy_server 铁律: 微信服务器主动请求 → 绝不能被 301