上周五晚上，一个开发者朋友发来消息："支付一直调不起来，用户都在催，老板在骂，我快疯了。"我看了他的代码，发现问题很简单——签名算法少了一个字段。但这个"简单"的问题，他折腾了整整6个小时。
这就是小程序支付的现实：出问题的地方往往不在你想象的地方。
本文不聊那些百度能搜到的API文档，我假设你已经看过文档了。我们直接来聊那些文档里不会告诉你的实战经验，包括我是怎么踩坑的，以及踩坑之后总结出的"避坑指南"。
一、先把准备工作做扎实：商户号和API密钥配置
很多人一上来就想写代码，结果配了半天环境发现用不了。小程序支付的第一步，是把基础设施搭好。
你需要准备这些东西：
商户号（mch_id）：在微信支付商户平台申请，这个没啥技巧，按流程来就行。
API密钥（APIv2）/ APIv3密钥：这个是关键，很多人栽在这里。APIv2用MD5签名，APIv3用RSA256，两套完全不同的体系。现在新接入建议用APIv3，老项目如果维护APIv2也别动它。
证书序列号：APIv3才需要，需要下载微信支付颁发的证书。这个证书要放在服务器上，千万别提交到Git仓库。我见过有人把证书传上去，然后账户被盗刷的。
小程序AppID和AppSecret：在小程序后台获取，AppSecret只显示一次，记得保存。
提醒一点：生产环境的配置和沙箱环境是完全分开的。开发阶段用沙箱，参数一样但接口地址不同，别混着用。
二、支付流程全景图：从前端到后端再到微信
很多人对支付流程只有一个模糊的印象，真正写代码的时候才发现不知道下一步该干嘛。我直接画个流程图给你们：
图：微信小程序支付完整流程
整个流程总结起来就是三步：
第一步：前端请求下单
小程序调用 wx.login() 获取 code，然后把商品信息和 code 发给后端。
第二步：后端统一下单
后端带着商户号、订单信息、回调地址去微信支付API下单，微信返回 prepay_id。
第三步：前端调起支付
后端把 prepay_id 和签名参数返回给小程序，小程序调用 wx.requestPayment() 调起支付。
看起来很简单对吧？但魔鬼都在细节里。
三、核心代码实现：三个关键环节
3.1 统一下单：后端的核心战场
后端代码用什么语言都行，我用 Node.js 举例，逻辑是相通的。
// 统一下单核心代码
async function unifiedOrder(orderData) {
const params = {
appid: config.appId,
mch_id: config.mchId,
nonce_str: generateNonceStr(), // 必须随机字符串
body: orderData.body, // 商品描述
out_trade_no: orderData.orderId, // 商户订单号
total_fee: orderData.amount * 100, // 金额，单位分！
spbill_create_ip: orderData.ip,
notify_url: config.notifyUrl,
trade_type: 'JSAPI',
openid: orderData.openid // 必须有！
};
// 生成签名 - 这里最容易出错
params.sign = generateSign(params, config.apiKey);
const result = await request({
url: 'https://api.mch.weixin.qq.com/pay/unifiedorder',
method: 'POST',
body: xmlBuilder.buildObject(params)
});
return parseXml(result);
}
重点提醒：金额单位是分，不是元。这个错误我见过不下10次。
签名生成有个坑：有些人直接拿 JSON 对象排序后拼接，但微信要求某些字段不参与签名计算。空值字段不要参与签名，加了反而过不了。
3.2 前端调起支付：三行代码但参数要对
// 小程序端支付调起
async function requestPayment(orderResult) {
const paySign = await getPaySign(orderResult.prepay_id);
return wx.requestPayment({
timeStamp: paySign.timeStamp,
nonceStr: paySign.nonceStr,
package: `prepay_id=${orderResult.prepay_id}`,
signType: 'RSA', // 或 'MD5'，取决于后端
paySign: paySign.sign
});
}
注意 package 参数，值必须是 prepay_id=xxx 的格式，前面不能有空格，微信会严格校验。
四、我踩过的那些坑：常见问题汇总
做了这么多支付项目，这几个问题出现频率最高：
坑1：签名一直报错"签名错误"
这个问题我刚工作那年就遇到过，当时排查了一整天。
可能原因：
我现在的做法是：先把所有参数打印出来，手动在微信签名校验工具里验证，确认没问题再对比代码逻辑。
坑2：支付成功但回调没收到
这种情况排查思路：
- 检查 notify_url 能否被外网访问（不能用 localhost）
- 回调必须返回 SUCCESS 的 XML，不返回或返回其他内容微信会反复重试
- 做好幂等性处理
回调处理代码示例：
// 支付回调处理
function handleNotify(data) {
// 1. 验证签名
if (!verifySign(data)) {
return '<xml><return_code>FAIL</return_code></xml>';
}
// 2. 检查订单状态
const order = getOrder(data.out_trade_no);
if (order.status === 'paid') {
return '<xml><return_code>SUCCESS</return_code></xml>';
}
// 3. 更新订单状态
updateOrderStatus(data.out_trade_no, 'paid');
// 4. 返回成功
return '<xml><return_code>SUCCESS</return_code></xml>';
}
坑3：用户取消支付后无法重新下单
这个是业务逻辑问题。很多人会遇到"当前订单号已存在"的报错。
原因是微信支付的订单号有规则：同一笔订单不能重复发起支付。
解决方案：
- 或者在数据库里标记原订单为"已取消"，允许用同一个订单号（需要和微信确认）
五、实战案例：一个完整的电商下单流程
说了这么多，来个真实场景。我做过一个社区团购小程序，支付流程是这样的：
- 点击结算，前端调用
/api/order/create 创建订单 - 前端调用
/api/payment/prepare 发起支付 - 后端调用微信统一下单接口，获取 prepay_id
- 后端对 prepay_id 做二次签名，返回调起参数
- 前端调用
wx.requestPayment() 调起支付
整个流程最关键的一点：不要相信前端，前端传来的支付结果不可信。必须以微信回调为准。前端支付成功不等于真正支付成功，只有回调通知才是最终确认。
六、写在最后：几个实用的建议
- 沙箱测试要彻底
- 日志要详细
- 回调要快
- 安全意识要强
支付功能说难不难，说简单也不简单。关键是理解它的原理，知道每个环节在做什么，出问题的时候才能快速定位。
