小程序如何对接微信支付：从商户号到第一笔回调

一、前置条件：先把账号关系理清

• 小程序主体完成微信认证（个人主体开不了微信支付）
• 申请微信支付商户号，支持企业、个体工商户、事业单位等
• 小程序 AppID 与商户号互相绑定
• 商户平台配置 APIv3 密钥、下载商户 API 证书

💡 小程序支付和公众号 JSAPI 支付共用一套下单接口，但小程序不需要配置 JSAPI 支付授权目录。

二、整体流程全景

1. 用户点「立即支付」，小程序把订单信息发给自家后端
2. 后端调用微信支付 JSAPI / 小程序下单接口，拿到 prepay_id
3. 后端按规则签名，把 timeStamp / nonceStr / package / signType / paySign 返给前端
4. 前端调 wx.requestPayment 拉起收银台
5. 用户支付完成后，微信回调后端 notify_url，后端验签、解密、更新订单

三、后端：调用 JSAPI 下单

接口地址

POST https://api.mch.weixin.qq.com/v3/pay/transactions/jsapi

核心参数

{
  "appid": "wx1234567890",
  "mchid": "1900000109",
  "description": "商城-订单支付",
  "out_trade_no": "ORDER20261020001",
  "notify_url": "https://api.example.com/wxpay/notify",
  "amount": {
    "total": 1990,
    "currency": "CNY"
  },
  "payer": {
    "openid": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o"
  }
}

⚠️ out_trade_no 必须唯一，重复会报订单号冲突；超时未付的订单应先关单再用新订单号重下。

四、前端：wx.requestPayment 调起支付

wx.requestPayment({
  timeStamp: '1697780000',
  nonceStr: '5K8264ILTKCH16CQ2502SI8ZNMTM67VS',
  package: 'prepay_id=wx2026102000001234567890',
  signType: 'RSA',
  paySign: 'oR9d8PuhnIc+YZ8cB...',
  success(res) {
    // 仅做页面跳转，不代表支付成功
  },
  fail(res) {
    if (res.errMsg.includes('cancel')) {
      // 用户取消
    }
  }
})

• package 值必须是 prepay_id=xxx 完整串，不是只传 id
• signType 与后端签名方式保持一致，V3 用 RSA，别套旧教程的 MD5
• success 回调只能说明「拉起支付没报错」，不能证明到账

五、后端：接收支付回调（最关键）

1. 验签

• Wechatpay-Serial
• Wechatpay-Signature
• Wechatpay-Timestamp
• Wechatpay-Nonce

2. 解密

{
  "out_trade_no": "ORDER20261020001",
  "transaction_id": "4200001234567890",
  "trade_state": "SUCCESS",
  "amount": { "total": 1990 }
}

3. 业务处理 + 应答

1. 验签
2. 解密
3. 查本地订单，做幂等判断（已处理直接返回成功）
4. 校验金额、订单号是否对得上
5. 更新订单状态、发货、记日志
6. 5 秒内返回 HTTP 200/204

// 成功不应答包体，状态码 200 即可

⚠️ 微信回调会重复推，必须幂等；超时未应答会按 15s/30s/3m… 重发最多 15 次。

六、兜底：别只信回调

• 前端 requestPayment 返回后，调后端查单接口确认状态
• 后端对「已创建但未支付」的订单，定时跑批查 查询订单 接口
• 超时未付调用关单接口，释放库存

七、常见坑速查

• 签名错误​ → 检查 appid 是不是小程序 appid、参数大小写、key/v3密钥用错、MD5/RSA 混用
• 回调收不到​ → notify_url 非公网、带端口、HTTP、服务器防火墙拦了
• 前端 paySign 报错​ → package 没带 prepay_id= 前缀
• 交易类小程序调不起支付​ → 未接入订单发货管理，被公众平台限权
• 金额对不上​ → 前端展示用元，后端传分，别直接透传

八、最小落地清单

• [ ] 小程序已认证、商户号已绑定 AppID
• [ ] APIv3 密钥和商户证书已配
• [ ] 后端能调通 JSAPI 下单拿到 prepay_id
• [ ] 前端 wx.requestPayment 参数由后端签名
• [ ] notify_url 公网 HTTPS、幂等处理
• [ ] 回调验签 + 解密 + 5 秒内应答
• [ ] 订单状态以后端查单/回调为准