35 lines
2.3 KiB
Markdown
35 lines
2.3 KiB
Markdown
# 微信生态接入契约
|
||
|
||
## 元数据
|
||
|
||
- 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 版本、认证、通知或重试语义变化时更新本文。
|