小程序开发：微信支付对接与避坑

在小程序开发中，微信支付几乎是所有电商、知识付费、生活服务类应用的标配能力。但真正动手接入后，你会发现它涉及商户号、证书、签名、回调、退款等多个环节，稍有不慎就会卡在“支付失败”上。这篇文章把我踩过的坑和完整流程整理出来，帮你少走弯路。

一、接入前的准备工作

微信支付的接入并不是只写几行小程序代码就能完成的，它需要三端配合：小程序端、自己的服务端、微信支付平台。开始前请先确认以下材料齐全：

• 已认证的小程序，并开通微信支付能力（在微信公众平台“微信支付”入口申请或绑定已有商户号）。
• 微信支付商户号（mchid），以及商户平台的管理员权限。
• APIv3 密钥、商户 API 证书（apiclient_cert.pem / apiclient_key.pem）。
• 一个已备案的 HTTPS 域名，用于接收支付结果通知。

注意：小程序支付要求用户 openid 必须与商户号 appid 对应。如果小程序和商户号主体不一致，需要先完成关联，否则统一下单会报“appid 与 mchid 不匹配”。

二、完整支付流程

微信支付的核心流程可以概括为四步：

1. 小程序调用 wx.login 拿到 code，服务端换取用户 openid。
2. 服务端调用微信支付统一下单接口（JSAPI 下单），拿到 prepay_id。
3. 服务端对 prepay_id 等参数做二次签名，返回给小程序。
4. 小程序调用 wx.requestPayment 拉起支付，支付成功后微信异步通知服务端。

服务端下单示例（Node.js）

下面用官方的 wechatpay-node-v3 风格演示关键参数，重点看签名和返回结构：

const params = {
  appid: 'wx1234567890',
  mchid: '1900000109',
  description: '测试商品',
  out_trade_no: 'ORDER_' + Date.now(),
  notify_url: 'https://your.domain.com/wxpay/notify',
  amount: { total: 1, currency: 'CNY' },
  payer: { openid: userOpenid }
};
// 调用 /v3/pay/transactions/jsapi 得到 prepay_id
const prepayId = res.prepay_id;
// 二次签名，返回给小程序
const payParams = signPayParams(appid, prepayId);

小程序端拉起支付

wx.requestPayment({
  timeStamp: payParams.timeStamp,
  nonceStr: payParams.nonceStr,
  package: payParams.package,
  signType: 'RSA',
  paySign: payParams.paySign,
  success() { /* 支付成功，但以后端通知为准 */ },
  fail(err) { console.error('支付失败', err); }
});

特别提醒：wx.requestPayment 的 success 只代表用户完成了支付动作，不能作为发货依据。真正的支付结果必须以服务端收到的异步通知为准。

三、常见问题与排查

1. 签名错误（SIGN_ERROR）

最常见。原因通常是：签名串拼接顺序错误、时间戳单位是秒不是毫秒、APIv3 密钥填错、或者证书序列号与私钥不匹配。建议先用官方签名校验工具验证，再检查换行符和编码。

2. 回调一直收不到

• notify_url 必须是公网 HTTPS，不能带参数或端口（默认 443）。
• 服务器防火墙要放行微信支付 IP 段。
• 回调必须返回 {"code":"SUCCESS","message":"成功"}，否则微信会持续重试。

3. 支付成功但订单状态没变

多数是回调处理逻辑没做幂等，或者回调里又去请求了需要鉴权的接口导致超时。建议先入库记录原始通知，再异步处理业务。

4. 退款与对账

退款接口同样需要证书，且退款结果也是异步通知。对账建议每天下载账单，用 out_trade_no 与本地订单核对，避免漏单。

5. 沙箱与真机调试

微信支付没有传统意义上的沙箱环境，测试时建议用 1 分钱真实下单。开发者工具里无法真正拉起支付，必须用真机预览。

四、几点实战建议

• 把支付相关逻辑全部放在服务端，小程序端只负责拉起和展示结果。
• 订单表增加 transaction_id、out_trade_no、pay_status 字段，方便对账和退款。
• 回调接口做好验签、解密和幂等，日志保留至少 90 天。
• 金额统一用“分”存储，避免浮点误差。

微信支付对接本身并不复杂，难的是把异常分支和资金安全考虑周全。把上面这些点落实，你的小程序开发支付模块基本就能稳定上线了。