微信生态接入契约
元数据
- Owner：支付与微信生态维护人
- 实现：
pkg/wechat/ - SDK：
github.com/ArtisanCloud/PowerWeChat/v3 v3.4.38 - 核验日期：2026-08-07
当前实际使用范围
系统使用公众号 OAuth、小程序 code2session、微信支付 JSAPI/H5 下单、查单、关单和支付通知。支付同时存在 PowerWeChat/v3 适配与仅配置 APIv2 Key 时使用的 v2 XML 适配；不得仅凭 SDK 文档推断其他微信能力。
端点、配置与关键字段
- 小程序：
GET https://api.weixin.qq.com/sns/jscode2session，参数为 AppID、AppSecret、临时 code 和固定authorization_code；响应必须含 OpenID、SessionKey，可选 UnionID；超时 10 秒。 - 支付 v2：
POST https://api.mch.weixin.qq.com/pay/unifiedorder和/pay/orderquery，XML + MD5 签名；关键字段为商户订单号、金额（分）、OpenID、交易类型、通知地址和客户端 IP。 - 支付 v3/SDK：使用 AppID、商户号、APIv3 Key、证书序列号、私钥及通知地址，支持 JSAPI/H5、Query、Close 和 Notify。
配置来自支付配置记录，不在本文列出具体值。v2 下单同时要求 return_code=SUCCESS 与 result_code=SUCCESS；查单以商户订单号关联本地支付。
回调、幂等、失败与重试
v2 按 API Key 验签，v3 按平台证书验签并解密通知。商户订单号是渠道幂等标识；通知还需核对金额、配置和本地状态，并以状态条件更新避免重复入账。小程序 errcode!=0、关键字段缺失、HTTP/解析失败均映射统一微信错误。
适配器没有对创建支付做盲目自动重试；查单可由业务流程补偿，关单和回调按原商户订单号及状态保持幂等。
安全与验证
AppSecret、API Key、私钥、证书内容、SessionKey、完整 OpenID 和通知原文不得进入文档或普通日志。可复现静态证据：pkg/wechat/miniapp.go、pkg/wechat/payment.go、pkg/wechat/payment_v2.go、internal/handler/callback/payment.go。真实验收需隔离商户验证 JSAPI/H5、查关单、签名失败、金额不符与重复通知；本次不调用真实渠道。
官方参考：https://pay.weixin.qq.com/doc/v3/merchant/4012065342
SDK、API 版本、认证、通知或重试语义变化时更新本文。