微信小程序支付接入全流程：5步完成商户号配置与API对接
微信小程序的支付，听起来像是“调个接口、传个参数”那么简单，但实际开发中，很多开发者会在“预下单-调起支付-结果回调”这个闭环里踩坑。今天就拆开揉碎了讲，从业务逻辑到代码细节，帮你把这条链路彻底打通。
先明确一个核心概念：小程序支付必须依赖微信支付服务端API，不能直接在前端用JS调用支付接口。整个流程就像你委托一个中间人（你的后端）去跟微信支付系统打交道，拿到“通行证”后再交给小程序前端去唤起支付界面。
一、支付前的准备：别在基础配置上翻车很多新手卡在第一步——参数配置。登录微信支付商户平台（pay.weixin.qq.com），找到“产品中心-开发配置”。这里有个容易被忽略的细节：JSAPI支付授权目录必须精确到页面路径。比如你的支付页面在 pages/order/pay，那授权目录就要填 https://你的域名/pages/order/pay，而不是只填到域名层级。否则调起支付时会直接报“当前页面的URL未注册”。
另一个常见问题是商户号与小程序AppID的绑定关系。在商户平台“产品中心-AppID账号管理”里，必须把小程序AppID绑定到商户号。如果用的是服务商模式，还要确认特约商户的授权关系。曾经有个团队因为用了测试号绑定正式商户号，导致线上支付一直弹不出界面，排查了一整天。
二、预下单：后端的关键一步预下单接口（https://api.mch.weixin.qq.com/pay/unifiedorder）是整个支付的起点。这里有一个容易被误解的参数：spbill_create_ip。以为是用户手机的IP，实际上微信支付要求传的是“调用微信支付API的服务器IP”。如果你用云函数或服务器集群，最好是固定一个出口IP，或者用request.context.environment这类方式获取当前服务器的真实IP。否则频繁变化可能导致风控拦截。
另一个容易出错的点是notify_url（支付结果回调地址）。这个地址必须公网可访问，且不能带参数（如 ?orderId=123 这种格式会被微信拒绝）。建议单独写一个支付回调接口，不要跟业务逻辑混在一起。回调接口返回的数据格式必须是XML，而且要在收到微信通知后立即返回“SUCCESS”，否则微信会重复通知（最多重试9次）。
举个实际案例：某电商小程序在回调里做了大量数据库写入操作，导致响应超时，微信反复通知，最终订单状态被重复更新。解决方案是：在回调里只做幂等性校验——先根据 transaction_id 查询订单是否已处理，未处理则更新状态并返回SUCCESS，已处理则直接返回SUCCESS。
后端拿到预下单返回的 prepay_id 后，需要生成调起支付所需的参数包（timeStamp、nonceStr、package、signType、paySign）。这里有一个致命的坑：签名字段必须严格按照微信文档的顺序拼接。比如 appId、timeStamp、nonceStr、package、signType 这个顺序不能乱，而且package参数的值必须是 prepay_id=xxx 的格式，不能只传 prepay_id 的ID。
很多开发者喜欢用现成的SDK生成签名，但SDK版本差异可能导致参数顺序错误。建议自己写一个签名函数做双重校验：先按微信文档手动算一次签名，再跟SDK生成的对比。我曾经遇到过一个坑：微信支付的签名算法在2019年后要求signType默认用MD5，但旧版SDK默认是HMAC-SHA256，导致高版本微信客户端调不起支付。
前端代码调用 wx.requestPayment 时，注意不要用异步函数包裹这个API。微信的支付接口是同步调起界面的，如果你在 wx.requestPayment 外面套了 setTimeout 或 Promise，可能会因为上下文丢失导致支付界面闪退。正确写法是直接调用：
wx.requestPayment({
timeStamp: '...',
nonceStr: '...',
package: 'prepay_id=...',
signType: 'MD5',
paySign: '...',
success: (res) => { /* 支付成功，但这里不要立刻跳转页面 */ },
fail: (err) => { /* 支付失败或取消 */ }
})
很多开发者以为 wx.requestPayment 的 success 回调就代表支付成功，这是大错特错的。这个回调只能说明用户输入了密码并完成了手机端的支付操作，但微信支付系统可能还没把结果同步到你的服务器。比如用户支付时网络中断，微信客户端显示成功，但服务器端根本没收到回调。
正确的做法是：在 success 回调里只做UI提示（如“支付中，请稍后”），然后主动轮询后端接口。后端接口根据订单号去微信支付查询订单状态（https://api.mch.weixin.qq.com/pay/orderquery），或者等回调通知到达后再更新订单状态。轮询间隔建议5秒一次，最多轮询10次。如果超过1分钟还没确认，引导用户去订单列表手动刷新。
这里有一个实用技巧：在预下单时生成一个 out_trade_no（商户订单号），并把它作为 attach 参数传给微信。这样在回调通知里，你可以通过 attach 快速定位到业务数据，而不用解析 out_trade_no 的格式。比如你的订单号是 ORD20231001，可以把 attach 设为 {"orderId":"ORD20231001"}，回调时直接 JSON.parse 即可。
支付完成只是开始，退款接口（https://api.mch.weixin.qq.com/secapi/pay/refund）需要双向证书认证。很多开发者在服务器上只配置了API密钥，忘了上传商户证书（apiclient_cert.p12或pem文件）。退款请求必须用证书签名，否则会报“CERT_ERROR”。建议把证书文件放在服务器安全目录，并设置读写权限为600。
对账方面，微信支付每天会生成对账单（https://api.mch.weixin.qq.com/pay/downloadbill），但格式是CSV或GZIP压缩的文本。不要手动下载，写个定时任务每天凌晨拉取前一天的账单，比对订单金额和手续费。曾经有团队因为手续费率配置错误（比如把0.6%误配成0.06%），半年损失了十几万。
如果遇到对不上的情况，优先查 trade_state 字段。微信支付有“SUCCESS”、“REFUND”、“NOTPAY”等状态，但还有一个容易被忽略的“REVOKED”（已撤销）。比如用户支付后立即取消，微信可能会先返回SUCCESS，再异步返回REVOKED。这时候你的订单状态如果只靠一次回调判断，就会变成“已支付但实际已撤销”的脏数据。
1. “支付验证签名失败”：90%的情况是参数顺序或大小写问题。检查 paySign 的拼接字符串是否包含换行符或空格，微信的签名算法要求所有参数值必须是原始字符串，不能做URL编码。
2. “当前页面无权限”：除了授权目录问题，还要检查小程序是否在微信开发者工具里预览。工具里的“真机调试”模式不支持支付，必须用“预览”生成二维码扫码测试。
3. “用户取消支付”：wx.requestPayment 的 fail 回调里，err.errMsg 是“requestPayment:fail cancel”才代表用户主动取消，其他错误（如“requestPayment:fail system error”）需要提示用户重试。不要一刀切地显示“支付失败”，否则用户以为钱扣了但没成功。
4. “退款金额超限”：微信支付规定单笔退款不能超过原订单金额，而且退款次数有限制。如果你的业务需要部分退款（比如退货只退一件商品），务必在退款前校验退款总额是否小于等于原订单金额减去已退款金额。
最后补充一个容易被忽略的点：微信支付在2023年后不再支持HTTP协议，所有接口必须走HTTPS。如果你的服务器用的是自签名证书，微信支付API会直接拒绝连接。建议用Let's Encrypt免费证书，或者云服务商提供的负载均衡来终结SSL。
小程序支付就像一场接力赛，前端、后端、微信支付三方必须步调一致。任何一个环节的时序错乱（比如先调起支付再生成订单），都会导致数据不一致。最好的做法是：在预下单前先锁定库存或生成订单草稿，支付成功后再正式扣减库存。这样即使支付失败，也能回滚操作，避免超卖。
