WeChat Mini Program Payments

微信支付,不止一种“接法”

真正要选的是后端如何创建订单、签名和接回调。小程序端最后通常都会调用 wx.requestPayment

01MVP 会员案例继续用 CloudPay;模板把支付做成可替换适配器,同时支持集成中心。

小程序通过三种后端路径连接微信支付,并通过异步回调更新订单与会员权益

先分清四层

很多讨论把客户端 API、后端接入、商户关系和业务状态混在一起,才会看起来像有十几种方案。

01

客户端收银台

wx.requestPayment 只负责调起支付,不负责可信地下单。

02

后端接入

CloudPay、集成中心或自建 API v3,三选一或做成适配器。

03

商户关系

普通商户与服务商/子商户是账户关系,不是另一套前端 API。

04

业务履约

订单、会员、退款和发货必须由异步回调驱动,并保证幂等。

1. 选择商品客户端只传 SKU 或业务 ID
2. 创建订单服务端读取金额并写入 PENDING
3. 统一下单由支付适配器生成签名参数
4. 调起支付wx.requestPayment
5. 异步回调验签、核对金额、幂等更新
6. 发放权益PAID 后再开会员或发货

三条主流后端路径

第三方聚合支付也可以接,但它本质上是另一种后端 Provider。通用模板不应默认增加费用和平台锁定。

路径 A · 最省配置

CloudPay 云调用

云函数调用 cloud.cloudPay.unifiedOrder,无需自行处理证书和签名,回调也进入云函数。

  • 适合CloudBase 原生小程序、单一 JSAPI 支付
  • 优点链路短、私有链路、运维少
  • 代价依赖 CloudBase 云调用和已配置的商户关系
腾讯官方说明 ↗
路径 B · V3 托管

CloudBase 集成中心

平台生成 HTTP 云函数并托管 APIv3 凭证。小程序通过 wx.cloud.callHTTPFunction 调用。

  • 适合新商户、需要查单/关单/退款等完整 V3 能力
  • 优点凭证托管、回调验签和解密由平台处理
  • 代价首次要准备 7 项凭证,业务回调仍需自己实现
腾讯官方说明 ↗
路径 C · 完全自控

自建微信支付 API v3

自己的服务端直接请求微信支付 API,自己管理私钥、签名、验签、解密、回调地址和证书轮换。

  • 适合已有支付中台、多端共用或复杂商户体系
  • 优点部署、数据和业务编排完全可控
  • 代价安全与运维责任最大,不适合当 AI 模板默认值
微信支付 APIv3 官方 SDK ↗

01MVP 的选择

最佳实践不是追最新名词,而是让业务订单与具体支付通道解耦,并选择当前项目里风险最低的通道。

通用代码模板

一个协议,两种官方适配器

  • cloudpay:CloudBase 原生项目的默认适配器。
  • integration-center:需要 APIv3 托管能力时启用。
  • custom-v3:只保留扩展点,不提供默认生产实现。
  • disabled:本地开发和不接支付的项目显式关闭。

无论选哪条路,都不能省

这些约束比 Provider 名字重要,也是 AI 生成代码最容易漏掉的地方。

金额归服务端

客户端不能传可信金额。服务端按 SKU、优惠规则和订单上下文计算。

回调才是支付事实

wx.requestPayment.success 只代表客户端流程完成,不能直接发放权益。

回调必须幂等

重复通知不能重复开会员、发货或记账;同时核对商户、AppID、订单号和金额。

订单状态可追溯

至少保存 PENDING、PAID、CLOSED、REFUNDING、REFUNDED,并记录支付流水。

业务层不认识 SDK

页面和会员服务只调用统一 PaymentGateway,不直接散落 CloudPay 或 V3 字段。

支付必须真机验收

覆盖成功、取消、重复回调、掉线后查单、退款和权益一致性,不用模拟成功代替。