简介C#/.NET 微信支付封装源码包内含二维码扫码支付、APP 发起微信支付等常用接口调用实现面向需要快速对接支付能力的 .NET 后端开发者。无论要集成扫码收银、处理 App 内支付还是需要理解微信支付服务端签名与回调流程这套源码都能直接参考或二次改造。资源压缩包共 151 个文件以 cs 源文件为主体辅以 xml 配置与文档、dll 依赖库、cshtml 页面视图及 nuspec/nupkg 等 NuGet 打包相关文件整体大小约 3.04MB结构相对完整。从项目入口、配置文件与核心支付封装类可以看出资源提供了可运行示例覆盖支付参数构造、签名、回调处理等关键环节便于开发者对照学习也能快速迁移到 MVC 项目中。目前已有超过 3200 人学习适合希望厘清微信支付服务端流程、提升开发效率的初中级 C# 工程师。1. C#/.NET 微信支付封装源码到底在“封装”什么微信支付官方给出的是 HTTP 接口文档不是开箱即用的 .NET SDK。任何接过微信支付的人都经历过同一件事下单要拼接 XML 或 JSON、加签名、带证书回调要解密、验签、回执退款要对账投诉要拉取光一个 JSAPI 下单就能写出一百多行重复代码。所谓「封装源码」就是把这一套离散、易错的请求流程收敛成几行可复用的 C# 方法让业务代码不再跟微信接口的细节纠缠。封装的核心价值不在“调用”而在“隔离”。接口地址、证书路径、商户号、APIv3 密钥这些配置被隔离在外部业务层只需传入订单金额、描述、用户 OpenId拿到初始化好的支付参数或者暴露一个回调处理入口剩下的签名、加密、HTTP 状态处理都在封装内部消化。适合的场景很明确.NET Framework 或者 .NET 6/8/9 环境下多项目复用同一套支付能力且对签名细节、回调安全、异常兜底有要求的团队。很多封装源码把精力放在“能用”但真正的难点是APIv3 的签名规则、平台证书轮换、回调验签的 AES-256-GCM 解密、重试与幂等设计。这四件事做扎实源码才算合格。接下来的每一章都围绕这四条展开。2. 微信支付 APIv3 依赖体系与 .NET 封装的边界划分2.1 三组基础依赖全局参数、签名算法与 HTTP 客户端微信支付 APIv3 的接口链路由三组依赖构成。第一是全局参数商户号mchid、APIv3 密钥、商户私钥实例、商户证书序列号、应用 AppId这些是每个请求都要用到的上下文对象。第二是签名算法所有请求都要用商户私钥对请求方法 请求路径 时间戳 随机串 请求体摘要做 RSA-SHA256 签名放进 HTTP 头里。第三是 HttpClient它承担连接复用和 TLS 握手。在 .NET 里划分封装边界时我一般会建三个命名空间层WechatPay.Config只放配置实体和加载逻辑WechatPay.Core放签名器、请求客户端、回调处理器不掺业务字段WechatPay.Business放 JSAPI 下单、Native 下单、退款、账单等具体业务方法。好处是后续换了证书、升级 API 版本或者接入服务商模式时只改中间层业务层代码不用动。封装源码最怕把签名逻辑和下单逻辑揉在一个类里那样一旦接口签名规则微调改动会波及所有调用方。2.1.1 内部变量与外部可见性的选择很多封装源码喜欢类内部存商户号、证书内容等字段并把 API 调用方法暴露成公共函数。这种做法在小项目中没毛病但放到长期维护的中大型系统里建议把配置对象以构造参数传入内部变量全部私有对外只暴露标准结果对象。例如下单方法不直接返回 HttpResponseMessage而是转成统一的PayResult或WxPayResponseT。这样调用方不需要处理 HTTP 状态码和响应体解析。C# 里常用的一种设计是把WechatPayOptions设成不可变对象属性只有 getter通过构造函数赋值防止运行期被意外篡改。证书和密钥比较适合放到配置文件或环境变量里跟代码仓库分离。封装是否优秀先看这一层拎得清不清楚。2.2 接口封装的两层含义HTTP 接口与业务接口微信支付封装里的“封装”指两层。第一层是 HTTP 接口封装负责把所有微信支付 REST 接口统一成一套调用模板构造签名、发请求、读响应。第二层是业务接口封装把“下单-回调-查单-退款”整条链路整理成业务语义清晰的方法组合。比如业务层叫CreateJsapiOrderAsync内部调用 HTTP 层HTTP 层根据配置自动选沙箱或生产地址。注意不要试图把所有业务动作合并成一个万能方法比如一个DoEverythingAsync。微信支付的业务闭环是分步骤的每一步都有独立状态合并会导致回调重放无法单独处理。2.3 封装继承多态在支付场景中的真实用处面向对象里的封装继承多态在支付封装里最常见的落地是“支付渠道抽象”。假如系统未来要接支付宝、银联可以定义一个IPaymentChannel接口包含CreateOrderAsync、VerifyNotifyAsync、QueryOrderAsync三个方法微信支付和支付宝各自实现。这样业务层只面向接口编程。当然如果确定只做微信支付不必强行加这一层抽象Useless abstraction 会被后来维护的人骂。除此之外同一套 HTTP 请求流程、不同的业务参数是策略模式的天然舞台。比如Native 下单和JSAPI 下单请求地址不同、参数不同但签名、读响应、验签完全一样封装一个通用的发送方法两个业务方法分别组装参数即可。3. 用 C# 与 .NET 实现微信支付客户端核心方法3.1 APIv3 请求签名的 C# 实现APIv3 要求每次请求携带Authorization: WECHATPAY2-SHA256-RSA2048头其中签名串的拼接格式是HTTP方法\nURL\n时间戳\n随机串\n请求体摘要\n五段用换行分隔请求体为空时摘要固定为sha256()的 hex 值。下面这段代码是签名器的核心部分using System.Security.Cryptography; using System.Text; public class WechatpaySigner { private readonly RSA _privateKey; private readonly string _merchantId; private readonly string _serialNo; public WechatpaySigner(string privateKeyPem, string merchantId, string serialNo) { _privateKey RSA.Create(); _privateKey.ImportFromPem(privateKeyPem); _merchantId merchantId; _serialNo serialNo; } public string BuildAuthorizationHeader(string method, string url, string body) { var timestamp DateTimeOffset.Now.ToUnixTimeSeconds().ToString(); var nonce Guid.NewGuid().ToString(N); var bodyHash Sha256Hex(body ?? string.Empty); var message ${method}\n{url}\n{timestamp}\n{nonce}\n{bodyHash}\n; var signature Convert.ToBase64String(_privateKey.SignData( Encoding.UTF8.GetBytes(message), HashAlgorithmName.SHA256, RSASignaturePadding.Pkcs1)); return $WECHATPAY2-SHA256-RSA2048 mchid\{_merchantId}\,nonce_str\{nonce}\,signature\{signature}\,timestamp\{timestamp}\,serial_no\{_serialNo}\; } private static string Sha256Hex(string input) { var bytes SHA256.HashData(Encoding.UTF8.GetBytes(input)); return Convert.ToHexStringLower(bytes); } }这段代码里最关键的两处是method必须是大写比如 POSTurl不需要包含域名只取路径部分Query 参数要完整带上。ImportFromPem是 .NET 5 之后的 API如果项目跑在 .NET Framework 4.7.2 上要改用RSA.FromXmlString配合证书转 XML 的方式或者引入 PemUtils 之类的解析库。签名算法用的是 PKCS1 填充的 SHA256不是 PSS也不能用 SHA1。微信支付在 2020 年后全面切换到 APIv3官方文档对这个签名串的拼写要求非常严格多一个换行或者少一个都会返回SIGN_ERROR。3.2 用 HttpClient 封装统一下单请求在 .NET 中正确使用 HttpClient 本身就值得单独聊。不要在每次请求时 new 一个实例会造成 socket 耗尽推荐用IHttpClientFactory或者静态单例 HttpClient。下面是统一下单的方法封装兼容 JSAPI 和 Nativepublic class WechatpayClient { private readonly HttpClient _httpClient; private readonly WechatpaySigner _signer; private readonly WechatpayOptions _options; public WechatpayClient(HttpClient httpClient, WechatpayOptions options) { _httpClient httpClient; _options options; _signer new WechatpaySigner( options.PrivateKeyPem, options.MerchantId, options.CertificateSerialNo); } public async TaskWxPayResponse CreateOrderAsync(WxPayOrderRequest request, CancellationToken ct default) { string url request.TradeType NATIVE ? https://api.mch.weixin.qq.com/v3/pay/transactions/native : https://api.mch.weixin.qq.com/v3/pay/transactions/jsapi; var payload JsonSerializer.Serialize(new { appid _options.AppId, mchid _options.MerchantId, description request.Description, out_trade_no request.OutTradeNo, notify_url _options.NotifyUrl, amount new { total request.TotalFen, currency CNY }, payer request.TradeType JSAPI ? new { openid request.OpenId } : null }, new JsonSerializerOptions { DefaultIgnoreCondition JsonIgnoreCondition.WhenWritingNull }); using var httpRequest new HttpRequestMessage(HttpMethod.Post, url); httpRequest.Headers.TryAddWithoutValidation( Authorization, _signer.BuildAuthorizationHeader(POST, url, payload)); httpRequest.Content new StringContent(payload, Encoding.UTF8, application/json); var response await _httpClient.SendAsync(httpRequest, ct); string body await response.Content.ReadAsStringAsync(ct); // 提取反序列化逻辑留出处理错误码的扩展点 return new WxPayResponse((int)response.StatusCode, body); } }参数说明TotalFen是整数类型的“分”不是 decimal 类型的“元”。微信支付不支持小数点金额金额都给整数分是 APIv3 的硬性约定。payer字段只对 JSAPI 下单有意义代码里通过JsonIgnoreCondition.WhenWritingNull保证 Native 下单时不会序列化一个 null 导致签名正文不一致。3.2.1 分账与元转分的注意事项热搜里微信虚拟支付代币数量支持小数点吗问的就是这类精度问题。虚拟支付的代币额如果支持 0.5 个代币建议先换算成“最小货币单位”再传给微信支付比如 1 代币 100 分那么 0.5 代币传 50。不要在 C# 里用 float 或 double 运算金额二进制浮点会带来误差用 int 或 long 做分整型溢出概率也小。封装里最好写一个MoneyConverter.ToFen(decimal yuan)扩展方法统一入口方便以后加舍入策略。3.3 APIv3 与 APIv2 的签名对比表老项目里还有不少 APIv2 的调用方式常见的是 MD5 或 HMAC-SHA256 签名参数用 XML 传输。封装源码里如果两版都在用要看清请求头构造差异。下表是两者的关键参数对比对比项APIv2 经典模式APIv3 接口BaseUrlhttps://api.mch.weixin.qq.com/pay/...https://api.mch.weixin.qq.com/v3/...请求体格式XMLJSON认证方式参数内签名Authorization 头携带商户签名签名算法MD5 / HMAC-SHA256RSA-SHA256商户私钥签名证书要求双向 TLS 商户证书单向 TLS无需加载客户端证书回调加密AES-256-ECB 或明文AES-256-GCM 带关联数据这个表在排查时会很有用。很多人拿着 APIv2 的证书配置去调 APIv3结果一直报PRIVATE_KEY_NOT_FOUND因为 APIv3 加载的是 apiclient_key.pem 而不是 apiclient_cert.p12。封装源码里要把这两个概念分开定义证书和私钥不要混用命名上也尽量贴近官方文件名减少团队沟通的歧义。4. 微信支付回调验签与解密中的易错点4.1 回调通知的验签逻辑为什么要检查五件事微信支付所有异步通知都会带Wechatpay-Timestamp、Wechatpay-Nonce、Wechatpay-Signature、Wechatpay-Serial四个响应头并发起一个序列号为对应平台证书的签名。完整的验签流程是五步取响应头里的时间戳判断与服务器当前时间差是否大于 5 分钟超过直接拒绝防止重放取响应体原文把时间戳\n随机串\n响应体\n拼成待验签串用Wechatpay-Serial找到对应平台证书公钥用 SHA256-RSA2048 做验签验签通过后才用 APIv3 密钥解密资源对象。常见错误是只验签不解密或者只解密不验签。验签不通过说明消息可能被篡改这时候去解密资源是危险的。另外很多封装源码喜欢在回调处理器里直接返回业务数据比如解锁订单、加积分一旦微信重试业务会执行两次所以幂等检查必须做在验签之后、业务处理之前。public bool VerifyNotificationHeaders(HttpRequestMessage request) { var timestamp request.Headers.GetValues(Wechatpay-Timestamp).First(); var nonce request.Headers.GetValues(Wechatpay-Nonce).First(); var signature request.Headers.GetValues(Wechatpay-Signature).First(); var now DateTimeOffset.Now.ToUnixTimeSeconds(); if (Math.Abs(now - long.Parse(timestamp)) 300) return false; var rawBody request.Content?.ReadAsStringAsync().Result ?? string.Empty; var message ${timestamp}\n{nonce}\n{rawBody}\n; using var publicKey LoadPlatformPublicKey(); // 拉取微信支付平台证书 return publicKey.VerifyData( Encoding.UTF8.GetBytes(message), Convert.FromBase64String(signature), HashAlgorithmName.SHA256, RSASignaturePadding.Pkcs1); }这里要注意网络请求的异步问题。回调处理接口如果写成public async TaskIActionResult Notify()那ReadAsStringAsync().Result有死锁风险在 ASP.NET Core 里尤其明显。正确做法是让整个方法异步到底验签方法本身也设计成Taskbool而不是在同步方法里阻塞拿结果。4.1.1 平台证书轮换对封装的额外要求微信支付的平台证书定期轮换封装里如果硬编码单一证书到期后回调验签全挂。常见做法是在本地维护一个证书缓存以序列号为 key验签时先查缓存缓存没有则回调微信平台证书接口拉取并校验下发的证书内容。这块逻辑要单独抽成一个PlatformCertificateProvider不掺进业务回调代码。提示平台证书接口本身也需要用商户私钥签名访问所以这个 Provider 要复用 3.1 节的内部签名器。4.2 AES-256-GCM 解密回调资源的 C# 实现APIv3 通知里的resource.ciphertext用的是 AEAD_AES_256_GCM 加解密。C# 里System.Security.Cryptography.AesGcm可以直接处理但它需要关联数据 AAD也就是请求资源里的associated_data字段。官方建议关联数据取值为transaction资源类型不同关联数据也可能不同。解密代码如下public string DecryptResource(string ciphertextBase64, string nonce, string associatedData, string apiV3Key) { byte[] ciphertext Convert.FromBase64String(ciphertextBase64); int tagSize 16; byte[] tag ciphertext[^tagSize..]; byte[] encryptedData ciphertext[..^tagSize]; byte[] nonceBytes Encoding.UTF8.GetBytes(nonce); byte[] aadBytes Encoding.UTF8.GetBytes(associatedData); byte[] plainBytes new byte[encryptedData.Length]; using var aes new AesGcm(Encoding.UTF8.GetBytes(apiV3Key), tagSize); aes.Decrypt(nonceBytes, encryptedData, tag, plainBytes, aadBytes); return Encoding.UTF8.GetString(plainBytes); }解密成功的前提是 APIv3 密钥正确、nonce取自通知资源内字段、关联数据不能为 null。微信回调报文里经常有编码坑比如密文里带和/用 Base64 字符串接收时没问题但在 JSON 反序列化时如果写错类型会直接抛异常。调试时先打印ciphertext前 32 位和后 32 位通常能分辨出是传参问题还是算法问题。4.3 网络层 ERR 与回调重试对封装的约束热搜词里net::err_incomplete_chunked_encoding是个浏览器的网络错误但把视角放回服务端它映射到回调方就是“响应被网关异常截断”。微信支付对这类情况有明确处理通知响应需要在 5 秒内返回成功回执{code:SUCCESS}如果没收到有效回执会持续重试 24 小时。这就倒逼回调处理逻辑必须在解密后立即落库然后立刻返回 SUCCESS业务后续动作异步去做。封装里我习惯把回调处理返回的WxPayNotifyResult分成三层接口设计如下public interface IWxPayNotifier { TaskNotifyResponse HandleNotifyAsync(NotifyRequest request); } public sealed record NotifyRequest( string RawBody, Dictionarystring, string Headers); public sealed record NotifyResponse(bool Success, string ReplyBody);这样实现方不需要关心底层验签但封装内部仍要保证两点HTTP 状态码必须返回 200重试时由于相同 out_trade_no 已经在仓储里应直接返回 SUCCESS 而不是再走一遍业务。5. 封装源码的进阶扩展方向与验证技巧5.1 解决 C# 循环数据采集和 UI 刷新卡顿的异步回调模型微信支付回调天然是异步进来的回到 C# 桌面程序或状态机里如果回调处理线程直接触碰 UI 控件很容易复现热搜中c# 循环数据采集和UI刷新卡顿的现场。封装层最好把回调结果通过ChannelT或SubjectT推给 UI 层而不是直接在回调线程里更新界面。比如 WinForms 里用Control.BeginInvoke是临时方案长时间跑数据采集时依然会卡顿因为消息队列被高频刷新消息塞满。一个更干净的方案是封装内部只做“数据解释”把解密后的支付成功对象塞进 ChannelUI 通过await foreach消费并批量刷新。这样即使一秒进来 50 个支付回调UI 线程也只按自己能处理的频率消费界面不卡业务状态也不丢。5.2 投诉回调与虚拟支付代币精度处理微信支付投诉回调是 2022 年后新增的推送类型封装源码需要独立处理。此类回调和支付回调共用同一个验签体系但resource里的字段完全不同包含complaint_id、amount、payer_openid等。在封装里可以扩展IWxPayNotifier接口的消费者注册机制按event_type分发到不同处理类这样不会因为新增回调类型而改动验签和解密主流程。虚拟支付的代币数量根据业务需要定义成最小单位如果后台允许 1.5 个代币传给支付系统时换算成 150 分校验侧也要统一用 long 比较避免 integer overflow。5.3 五分钟完成回调链路验证本地调试微信支付回调有历史难题微信服务器无法访问内网地址。我用得最多的技巧是用内网穿透工具配合临时域名把受信任域名指到本机端口验证顺序固定为三步先用curl手动构造一个 POST 请求带伪造的Wechatpay-Serial头确认回调接口在验签失败时返回 401 而不是 200用真实支付订单触发回调观察解密后日志里的 out_trade_no 是否与库中一致杀掉回调处理进程让微信重试确认重试到达时能正确返回重复回调的 SUCCESS 回执。最后一步极其关键能验证幂等设计是否真的生效很多人封装的回调接口在“只处理一次”的场景下没有问题一遇到重放就容易重复入账。封装源码不是写出来就算完真正的交付是被别的项目引用后配置凭据、注入IHttpClientFactory、注册回调路由二十行内能跑起来这才是封装这层抽象该有的状态。本文还有配套的精品资源点击获取