简介面向C#开发者的一套微信支付接口DEMO合集聚焦微信支付、企业支付到个人以及企业付款到零钱等场景适合需要快速理解接入流程、进行二次开发或排查支付问题的中初级.NET开发者。压缩包共93个文件、约2.13MB以47个cs源码和13个aspx页面为主辅以8个dll、5个config及少量js、sln与缓存文件涵盖SDK引用、Web示例、业务封装和运行配置。已有1575人学习。内容围绕cs_sdk_v3.0.9展开包含JSAPI支付、刷卡支付、扫码支付、企业付款、订单退款、订单查询、退款查询与账单下载等接口示例并提供签名验证、请求发送、结果处理代码可作为打通支付链路、对照参数配置和排查回调问题的参考。1. 从运营在后台点下「打款」那一刻说起分销、佣金、返现、活动奖励这类业务最后都归结到同一个动作把一笔钱从公司账户付给一个普通用户。后台点一下「打款」钱在几秒内进入用户零钱中间要走的是微信支付的企业付款到零钱现在官方叫商家转账到零钱接口而不是普通的下单支付。这两者最大的区别在于下单是收钱转账是付钱付钱那条链路必须带商户证书签名错一个字、证书少一个字节都会直接返回FAIL。这个 C# Demo 覆盖了三条链路微信支付统一下单JSAPI / Native、企业付款到个人零钱、企业付款到银行卡用最原始的 XML 报文加 MD5/HMAC-SHA256 签名手搓了一遍。它适合两类人一是刚接手「提现」「返佣」需求、需要一份能对照着改的骨架的后端二是想搞清楚微信支付 v2 那套签名规则到底怎么算、证书怎么挂的开发者。代码不长但每一段都踩在真实的坑上。2. 项目结构与技术选型三层骨架撑起一个能跑的支付 Demo2.1 目录结构把「能跑的 Demo」拆成三层很多支付 Demo 的问题是把所有东西塞进一个Program.cs跑起来是能跑改起来就是灾难。这个项目的做法是按职责切成三个工程业务层和协议层彻底分开。WeChatPayDemo/ ├─ src/ │ ├─ WeChatPay.Demo.Api/ # ASP.NET Core Web API对外暴露下单/转账/回调接口 │ │ ├─ Controllers/PayController.cs │ │ ├─ Controllers/TransferController.cs │ │ ├─ Program.cs │ │ └─ appsettings.json │ ├─ WeChatPay.Core/ # 与业务无关的支付能力可被任何项目引用 │ │ ├─ Options/WeChatPayOptions.cs │ │ ├─ Security/SignHelper.cs │ │ ├─ Security/CertificateProvider.cs │ │ ├─ Protocol/XmlHelper.cs │ │ ├─ Protocol/WeChatPayClient.cs │ │ └─ Models/UnifiedOrderRequest.cs │ └─ WeChatPay.Demo.Console/ # 控制台工程改完代码随手跑一笔不用起 Web ├─ certs/ # apiclient_cert.p12 等.gitignore 里必须排除 └─ tests/WeChatPay.Core.Tests/ # 签名用例拿官方文档给的示例串做断言WeChatPay.Core是这个项目的核心价值所在。里面没有一行业务代码全是「怎么把一个字典变成签名串」「怎么把一个字典变成 XML」「怎么用证书建一个 HttpClient」这类原子能力。业务层拿到它之后只需要负责组装参数、落库、判断结果。控制台工程看着多余实际调试时最省事改完SignHelperdotnet run一下就能看到签名串对不对不用走一遍完整的 HTTP 链路。certs/目录单独拎出来是有意的。证书文件和代码混在一起很容易在git add .的时候被提交上去一旦进了仓库历史删都删不干净血泪经验。2.2 技术选型为什么是 HttpClient 加自签工具类而不是上官方 SDK项目跑在 .NET 6 / .NET 8 上用到的全是框架自带的东西没有引第三方支付 SDK也没有引 JSON 库——因为 v2 接口的报文本来就是 XML。HttpClient所有请求走HttpClient转账类接口需要挂客户端证书所以用的是HttpClientHandler.ClientCertificates.Add()这条路子。这里有个前提一个HttpClient实例只挂一个证书多商户场景必须按商户号缓存实例不能共用一个静态单例。X509Certificate2加载apiclient_cert.p12密码就是商户号不是 API 密钥很多人第一次就填错。System.Xml.LinqXML 的组装和解析都用XElement不手拼字符串。手拼最容易在desc字段里带个或就炸掉。IOptions 配置模式商户参数统一走配置注入代码里不出现任何硬编码的 appid 和密钥。选择不用官方 SDK 的理由很直接v2 那套接口本质就是「表单参数 签名 XML」自己封一层出问题时能一眼看到发出去的原始报文长什么样。SDK 把报文藏在里面调试的时候反而像对着一个黑匣子。等业务稳定、需要接 v3 的时候再考虑换 SDK 也不迟。提示如果目标框架是 .NET Framework 4.xHttpClientHandler和X509Certificate2的用法基本一致但Convert.ToHexString这类 .NET 5 的 API 要换成BitConverter.ToString(bytes).Replace(-, )。2.3 配置与密钥证书、商户号、API 密钥分别放哪配置项集中在一个强类型类里字段名跟微信文档保持一致避免看代码时来回对译。public class WeChatPayOptions { public const string SectionName WeChatPay; public string AppId { get; set; } default!; // 公众号/小程序 appid public string MchId { get; set; } default!; // 商户号同时是 p12 证书密码 public string ApiKey { get; set; } default!; // APIv2 密钥32 位 public string CertPath { get; set; } default!; // apiclient_cert.p12 相对/绝对路径 public string NotifyUrl { get; set; } default!; // 必须公网可访问 public string ServerIp { get; set; } default!; // 服务器出口 IP不要填 127.0.0.1 }对应的appsettings.json长这样。注意ApiKey只放占位符真实值走环境变量或者部署平台的密钥管理别跟着代码一起进仓库。{ WeChatPay: { AppId: wx0000000000000000, MchId: 1900000000, ApiKey: , CertPath: certs/apiclient_cert.p12, NotifyUrl: https://your-domain.com/api/pay/notify, ServerIp: 203.0.113.10 } }注册的时候顺手把校验做掉配置缺项直接启动失败比跑到线上第一笔转账才发现ApiKey是空字符串要好得多。builder.Services.AddOptionsWeChatPayOptions() .Bind(builder.Configuration.GetSection(WeChatPayOptions.SectionName)) .Validate(o !string.IsNullOrWhiteSpace(o.AppId) !string.IsNullOrWhiteSpace(o.MchId) o.ApiKey?.Length 32, 微信支付配置不完整请检查 AppId / MchId / ApiKey) .ValidateOnStart();ApiKey长度固定 32 位这个校验能拦住一大半「签名错误」。因为密钥末尾多一个空格、或者复制的时候被换行截断现象都表现为签名不通过排查起来极其浪费时间。3. 核心链路拆解一笔企业付款到零钱从拼参数到拿回执的全过程3.1 签名所有接口的第一道门槛v2 接口的签名规则本身不复杂难在细节参与签名的字段必须是非空值必须排除 sign 字段本身必须按字段名 ASCII 升序排列最后拼上keyAPI密钥再做 MD5 或 HMAC-SHA256。任何一条不满足服务端算出来的就是另一个值。public static class SignHelper { /// summary /// 微信支付 v2 签名非空字段 排除 sign 字段名 ASCII 升序 末尾拼 key /// /summary public static string Build(IDictionarystring, string dict, string apiKey, string signType MD5) { var sb new StringBuilder(); foreach (var kv in dict.Where(p p.Key ! sign !string.IsNullOrWhiteSpace(p.Value)) .OrderBy(p p.Key, StringComparer.Ordinal)) { sb.Append(kv.Key).Append().Append(kv.Value).Append(); } sb.Append(key).Append(apiKey); // key 参与拼接但不参与排序 var raw sb.ToString(); if (signType HMAC-SHA256) { using var hmac new HMACSHA256(Encoding.UTF8.GetBytes(apiKey)); return Convert.ToHexString(hmac.ComputeHash(Encoding.UTF8.GetBytes(raw))).ToUpperInvariant(); } using var md5 MD5.Create(); return Convert.ToHexString(md5.ComputeHash(Encoding.UTF8.GetBytes(raw))).ToUpperInvariant(); } }几个参数和实现细节值得单独说。StringComparer.Ordinal是必须的不能用默认的OrderBy(p p.Key)因为默认比较器受当前区域性影响在某些环境里_和字母的相对顺序会不一样本地跑通、服务器报签名错误十有八九是这里。MD5 结果统一转大写HMAC-SHA256 在 v2 里也要求大写这两处微信文档写得不显眼但服务端是严格比对的。total_fee、amount这类金额字段在签名前就已经是字符串形态的整数分不要在这一层做任何格式化1000.00和1000算出来的签名不同。注意签名串里如果出现中文比如body字段编码必须是 UTF-8。用Encoding.Default在 Windows 上可能侥幸跑通换到 Linux 容器里就是另一回事。3.2 统一下单先把订单号、金额和回调地址组织好下单是所有支付链路的起点。这个 Demo 里统一下单走的是 JSAPI返回prepay_id之后前端还要再做一次签名才能调起收银台。public async TaskUnifiedOrderResult UnifiedOrderAsync(UnifiedOrderRequest req) { var dict new Dictionarystring, string { [appid] _opt.AppId, [mch_id] _opt.MchId, [nonce_str] Guid.NewGuid().ToString(N), // 32 位随机串每次都要换 [body] req.Body, // 展示在用户账单里别写内部代号 [out_trade_no] req.OutTradeNo, // 商户侧唯一退款和对账都靠它 [total_fee] req.TotalFeeFen.ToString(), // 单位是分不是元 [spbill_create_ip] req.ClientIp, [notify_url] _opt.NotifyUrl, [trade_type] JSAPI, [openid] req.OpenId, [sign_type] MD5 }; dict[sign] SignHelper.Build(dict, _opt.ApiKey); var xml XmlHelper.ToXml(dict); using var content new StringContent(xml, Encoding.UTF8, text/xml); var raw await _http.PostAsync(https://api.mch.weixin.qq.com/pay/unifiedorder, content) .Result.Content.ReadAsStringAsync(); var result XmlHelper.ParseUnifiedOrderResult(raw); if (result.ReturnCode ! SUCCESS || result.ResultCode ! SUCCESS) throw new WeChatPayException(result.ReturnMsg ?? result.ErrCodeDes, raw); return result; }参数里有三处容易出错。out_trade_no是幂等的锚点同一笔业务必须复用同一个单号重复下单微信会直接返回「订单号重复」notify_url必须是公网能访问的 https 地址本地开发想收回调只能靠内网穿透工具临时映射total_fee用int存储别用decimal微信只认整数分。拿到prepay_id之后前端还要再签一次名这次用的是timeStamp、nonceStr、packageprepay_idxxx、signType四个字段加同一个 API 密钥规则和上面完全一样可以直接复用SignHelper.Build。public JsApiPayParams BuildJsApiParams(string prepayId) { var dict new Dictionarystring, string { [appId] _opt.AppId, [timeStamp] DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString(), [nonceStr] Guid.NewGuid().ToString(N), [package] $prepay_id{prepayId}, [signType] MD5 }; dict[paySign] SignHelper.Build(dict, _opt.ApiKey); return new JsApiPayParams(dict); }3.3 企业付款到零钱带证书的那一条 POST这条接口和下单最大的差别是必须带客户端证书走双向 TLS。请求地址是mmpaymkttransfers/promotion/transfers字段名也和下单不一样叫mch_appid和mchid不是appid和mch_id。直接复制下单的字典过来改一定会报参数错误。public static HttpClient CreateClient(string p12Path, string mchId) { // 密码是商户号不是 API 密钥 var cert new X509Certificate2( p12Path, mchId, X509KeyStorageFlags.MachineKeySet | X509KeyStorageFlags.PersistKeySet | X509KeyStorageFlags.Exportable); var handler new HttpClientHandler(); handler.ClientCertificates.Add(cert); return new HttpClient(handler) { Timeout TimeSpan.FromSeconds(15) }; }X509KeyStorageFlags这三个标志是踩坑踩出来的。MachineKeySet让私钥落在机器级存储里容器环境下能避免用户级存储不可写的问题PersistKeySet保证多次加载同一个证书时私钥不丢Exportable在 Linux 上做 p12 重新导出时是必需的。少一个表现可能是CryptographicException也可能是「握手成功但服务端说没有证书」。转账本身的方法就清晰了参数组装完直接 POSTpublic async TaskTransferResult TransferAsync(TransferRequest req) { using var client CertificateProvider.CreateClient(_opt.CertPath, _opt.MchId); var dict new Dictionarystring, string { [mch_appid] _opt.AppId, // 注意是 mch_appid [mchid] _opt.MchId, // 注意是 mchid [nonce_str] Guid.NewGuid().ToString(N), [partner_trade_no] req.PartnerTradeNo, // 商户侧转账单号必须唯一 [openid] req.OpenId, // 必须与 mch_appid 同源 [check_name] req.CheckName, // NO_CHECK / OPTION_CHECK / FORCE_CHECK [re_user_name] req.RealName, // check_name 非 NO_CHECK 时必填 [amount] req.AmountFen.ToString(), // 单位分 [desc] req.Desc, // 展示在用户零钱明细写清楚用途 [spbill_create_ip] _opt.ServerIp }; dict[sign] SignHelper.Build(dict, _opt.ApiKey); var xml XmlHelper.ToXml(dict); using var content new StringContent(xml, Encoding.UTF8, text/xml); var resp await client.PostAsync( https://api.mch.weixin.qq.com/mmpaymkttransfers/promotion/transfers, content); var raw await resp.Content.ReadAsStringAsync(); var result XmlHelper.ParseTransferResult(raw); if (result.ResultCode ! SUCCESS) throw new WeChatPayException(${result.ErrCode}:{result.ErrCodeDes}, raw); return result; // 含 payment_no、payment_time落库留存 }check_name的取值直接决定风控强度NO_CHECK不校验实名单笔和单日额度最低FORCE_CHECK强校验必须传re_user_name且与用户实名一致OPTION_CHECK介于两者之间实名对不上会失败、不传则跳过。业务上如果是给陌生人打佣金建议FORCE_CHECK虽然麻烦但能挡住一批脏 openid。partner_trade_no是这张转账单的主键重复提交同一单号微信会返回失败而不是重复付款这一点比下单接口更严格也是幂等的天然屏障。3.4 回调与结果判读怎么确认钱真的到了企业付款到零钱这个接口成功返回里的result_codeSUCCESS只代表受理成功钱到没到账要以查询接口或用户零钱明细为准。这也是很多人第一次接的时候会误判的地方。回调本身是 XML POST 到notify_url处理逻辑分三步验签、幂等、返回规定的 XML。[HttpPost(/api/pay/notify)] public async TaskIActionResult Notify() { using var reader new StreamReader(Request.Body, Encoding.UTF8); var xml await reader.ReadToEndAsync(); var data XmlHelper.ToDictionary(xml); // 1) 验签用收到的全部字段重算一次 var calc SignHelper.Build(data, _opt.ApiKey); if (!string.Equals(calc, data.GetValueOrDefault(sign), StringComparison.OrdinalIgnoreCase)) return Content(XmlHelper.ToXml(Fail(签名校验失败)), text/xml); if (data.GetValueOrDefault(return_code) SUCCESS data.GetValueOrDefault(result_code) SUCCESS) { // 2) 幂等out_trade_no 上建唯一索引插入失败说明已处理过 await _orderService.MarkPaidAsync(data[out_trade_no], data[transaction_id]); } // 3) 必须返回这个格式否则微信会按 15s/15s/30s/3m/10m 的节奏重试 return Content(XmlHelper.ToXml(new Dictionarystring, string { [return_code] SUCCESS, [return_msg] OK }), text/xml); }return_code和result_code是两层含义前者代表通信层面是否成功后者代表业务层面是否成功。只有当两个都是SUCCESS时才是真正的支付成功。处理完业务后无论成功失败都要返回SUCCESS否则微信会持续重推把日志刷满。如果转账结果不确定比如网络超时走查询接口mmpaymkttransfers/gettransferinfo参数是appid、mch_id、partner_trade_no、nonce_str加签名同样要带证书。转账类业务里这个查询接口的使用频率其实比转账接口本身还高。4. 本地跑通从改配置到第一笔 0.01 元转账4.1 环境与前置条件代码之外的部分更难先把话说在前面这个 Demo 能跑起来一半靠代码一半靠商户平台那边的开通状态。以下条件缺一个代码再对也是白跑。已认证的服务号或小程序拿到AppId并且与商户号完成关联。商户平台已开通「企业付款到零钱」新版叫商家转账产品未开通时接口会直接返回无权限。已设置 32 位 APIv2 密钥注意设置后不可查看只能重置。已下载apiclient_cert.p12证书密码是商户号。商户平台里配置了服务器出口 IP 白名单spbill_create_ip要和它一致。本地开发想收回调notify_url需要一个公网可达的地址。开发环境用 .NET 8 SDK 就够还原和启动两条命令dotnet restore dotnet run --project src/WeChatPay.Demo.Api控制台工程更适合验证签名这类纯逻辑单元dotnet run --project src/WeChatPay.Demo.Console -- --sign-test4.2 证书与参数填写最容易翻车的一步把apiclient_cert.p12放进certs/目录CertPath指向它MchId填进去当密码。如果部署目标是 Linux 容器.NET加载 p12 有时会因为 OpenSSL 版本或证书里带的额外属性失败稳妥的做法是转成 PEM 再重新打包# p12 拆成证书和私钥密码是商户号 openssl pkcs12 -in apiclient_cert.p12 -clcerts -nokeys -out apiclient_cert.pem -passin pass:1900000000 openssl pkcs12 -in apiclient_cert.p12 -clcerts -nocerts -out apiclient_key.pem -passin pass:1900000000 # 重新导出成兼容性更好的 p12 openssl pkcs12 -export -in apiclient_cert.pem -inkey apiclient_key.pem \ -out apiclient_all.p12 -passout pass:1900000000加载的时候换成CreateFromPemFile再导出这条路在 Linux 上最稳var pem X509Certificate2.CreateFromPemFile(certPemPath, keyPemPath); var cert new X509Certificate2(pem.Export(X509ContentType.Pfx), mchId, X509KeyStorageFlags.MachineKeySet | X509KeyStorageFlags.Exportable);注意certs/目录必须写进.gitignore。证书一旦提交进仓库即使后面删除历史和 fork 里都还在。4.3 发起请求与读日志断点打在什么位置接口启动后先跑一笔转账。金额用 1 分就行既能验证链路又能控制成本。curl -X POST http://localhost:5000/api/transfer \ -H Content-Type: application/json \ -d {openId:o00000000000000000000000000000,realName:用户实名,amountFen:1,desc:佣金提现测试}调试阶段最有效的手段是在三个位置打日志签名前排好序的字典、发出去之前的完整 XML、收到的原始响应 XML。这三个东西一摆出来问题基本能定位到具体字段。日志里openid要脱敏只保留前 6 位和后 4 位ApiKey绝对不能出现。_logger.LogDebug(签名原文: {Raw}, raw); _logger.LogDebug(请求报文: {Xml}, xml); _logger.LogDebug(响应报文: {Xml}, responseXml);如果返回FAIL先看return_msg如果是SUCCESS但result_codeFAIL看err_code和err_code_des。这两组字段的含义完全不同混着看会走很多弯路。4.4 小额验证与对账确认钱真的到账1 分钱的转账提交成功后回到商户平台的交易记录里查partner_trade_no状态应该是「已付款」同时让对应用户打开零钱明细desc字段内容会原样显示在那里这也是为什么desc不要写内部订单号或者测试字样。接着调一次查询接口做闭环验证var query new Dictionarystring, string { [appid] _opt.AppId, // 查询接口这里又变回 appid / mch_id [mch_id] _opt.MchId, [partner_trade_no] partnerTradeNo, [nonce_str] Guid.NewGuid().ToString(N) }; query[sign] SignHelper.Build(query, _opt.ApiKey);注意查询接口的字段名是appid/mch_id和转账接口的mch_appid/mchid正好对调。同一个项目里两套命名写的时候很容易复制错建议在模型类上直接写注释标明来源接口。对账这块正式环境建议每天跑一次「本地转账记录 LEFT JOIN 微信交易记录」的比对找出本地标记成功但微信侧没成功的孤儿单以及微信侧成功但本地没登记的回调丢失单。5. 避坑与排查五条让我加过班的真实报错5.1 签名错误本地通过、服务器全挂现象很典型本地调接口一切正常发到测试环境之后所有请求统一返回return_codeFAIL/return_codereturn_msg签名错误/return_msg代码一个字没改。原因基本锁定在三个地方。一是配置读取的密钥末尾带了空格或换行Trim()能解决二是排序用了默认比较器跨区域性环境下_和字母顺序不一致三是某些字段在本地是 null 被跳过到了线上被某段逻辑赋成了空字符串空字符串在IsNullOrWhiteSpace里会被过滤但如果代码里判断的是! null就会参与签名多出一段attach。解决办法是固定一条排查路径把参与签名的原始串打印出来逐字符和官方文档给出的示例串比对而不是猜。同时配置类里对ApiKey做长度校验和Trim()处理从源头堵住。5.2 证书加载失败Linux 容器里的 p12 兼容问题现象是X509Certificate2构造时抛CryptographicException: The system cannot find the file specified或者更隐晦的unable to load certificate路径明明是对的。原因有两个层面。一是 p12 密码填错了很多人第一次填成了 API 密钥而正确的密码是商户号二是 .NET 在 Linux 上通过 OpenSSL 解析 p12旧版 OpenSSL 对某些加密算法和自定义属性支持不好Windows 能读的文件换到容器里就读不出来。另外容器镜像里如果没装ca-certificates握手阶段也会失败。解决方案分两步先用openssl pkcs12 -info在命令行确认这个 p12 能不能被当前系统读出来读不出来就按 4.2 节的流程转成 PEM 再重新导出容器基础镜像里显式安装ca-certificates和libssl相关包别指望 slim 镜像自带。5.3 金额与 openid报错信息最会骗人的两处现象之一是接口返回PARAM_ERROR反复检查参数名都对现象之二是接口返回SUCCESS但用户说没收到钱现象之三是直接OPENID_ERROR。原因分别是金额字段的单位是分业务层如果传的是decimal元再强转int9.99m会变成9少付了 99 分虽然不报错但金额对不上openid是有归属的公众号的 openid 和 小程序的 openid 不是同一个用 A 应用的 openid 去调 B 应用的转账接口服务端校验不通过。解决办法是把金额在领域模型入口就转成int分全链路不出现浮点数openid、appid一起存进用户表转账时校验二者的appid是否和配置里的一致不一致直接抛业务异常而不是发给微信。5.4 回调重复与丢单没有幂等表的代价现象是用户零钱到账了但本地订单状态一直停在「处理中」或者更糟同一笔回调进来三次账户余额被加了三遍。原因在回调处理端。订单状态没更新通常是处理逻辑抛了异常没被捕获或者返回体不是微信要求的 XML 格式微信认为没收到确认就一直重推。余额被重复加是因为处理逻辑没有幂等控制回调来一次就执行一次。解决办法是在out_trade_no或partner_trade_no上建唯一索引处理前先做一次插入尝试插入失败说明这单已经处理过直接返回成功业务处理放到事务里失败回滚返回非SUCCESS让微信重推而不是吞掉异常返回成功。5.5 IP 白名单与 spbill_create_ip最不像 bug 的 bug现象是接口时而成功时而失败或者直接返回无权限类错误日志里看不出任何规律。原因是spbill_create_ip填了这个字段但填的是127.0.0.1或者服务器做了多出口 NAT实际出口 IP 和商户平台白名单里配的那个不一致。微信侧对来源 IP 做校验多台机器负载均衡时只有部分请求会命中白名单。解决办法是把ServerIp做成配置项值填服务器的真实出口 IP从部署环境注入而不是硬编码多出口的场景要和运维确认稳定的出口地址或者把所有可能出口都加进白名单。6. 二次开发把 Demo 收成能上生产的一层封装Demo 到生产之间隔着三件事接口抽象、幂等落库、版本迁移。6.1 抽接口与多商户路由不要把WeChatPayClient直接注入到 Controller 里。抽一个业务语义的接口支付细节留在实现类public interface ITransferService { TaskTransferResult TransferToWalletAsync(string bizNo, string openId, int amountFen, string desc); } // 多商户按 key 取不同的 HttpClient 实例证书不能共用 public class WeChatPayClientFactory { private readonly ConcurrentDictionarystring, HttpClient _cache new(); public HttpClient Get(string mchId, string certPath) _cache.GetOrAdd(mchId, _ CertificateProvider.CreateClient(certPath, mchId)); }HttpClient按商户号缓存是因为一个实例只能挂一张证书。这一点在做 SaaS 多租户时特别关键早期用一个静态HttpClient到处传后面加第二个商户就得推倒重来。6.2 幂等表、重试与对账转账接口天然要求幂等partner_trade_no就是你的业务单号落库时建唯一索引。重试策略要区分错误码SYSTEMERROR、网络超时可以重试PARAM_ERROR、AMOUNT_LIMIT重试多少次都没用。重试前先调一次gettransferinfo查询确认上一笔到底是什么状态再决定要不要重发。对账任务每天跑一次比对本地转账表和微信交易记录把「本地成功、微信失败」的单子标出来人工介入。这块逻辑不复杂但它是唯一能在出事后把账扳平的手段。6.3 v2 到 v3 的迁移路线企业付款到零钱这条 v2 接口新商户号已经很难申请到权限了对应的替代品是 v3 的「商家转账到零钱」。差异不小报文从 XML 换成 JSON签名从 MD5 换成SHA256-RSA2048用商户私钥签名用平台证书验签请求头要带Authorization: WECHATPAY2-SHA256-RSA2048 ...证书体系也换成了商户 API 证书加平台证书两套。迁移不用推倒重来。把SignHelper和WeChatPayClient抽象成接口v2 和 v3 各写一个实现业务层依赖接口配置里加一个ApiVersion开关灰度的时候按商户号切。这样新老商户能并行跑一段时间比一次性全量切换安全得多。从那以后我每次接支付相关需求都是先把幂等表和回调日志这两件事落在业务代码之前再去写转账逻辑——钱这条链路上任何「应该不会重复」的假设最后都会被打脸。希望帮到你。本文还有配套的精品资源点击获取
简介面向C#开发者的一套微信支付接口DEMO合集聚焦微信支付、企业支付到个人以及企业付款到零钱等场景适合需要快速理解接入流程、进行二次开发或排查支付问题的中初级.NET开发者。压缩包共93个文件、约2.13MB以47个cs源码和13个aspx页面为主辅以8个dll、5个config及少量js、sln与缓存文件涵盖SDK引用、Web示例、业务封装和运行配置。已有1575人学习。内容围绕cs_sdk_v3.0.9展开包含JSAPI支付、刷卡支付、扫码支付、企业付款、订单退款、订单查询、退款查询与账单下载等接口示例并提供签名验证、请求发送、结果处理代码可作为打通支付链路、对照参数配置和排查回调问题的参考。1. 从运营在后台点下「打款」那一刻说起分销、佣金、返现、活动奖励这类业务最后都归结到同一个动作把一笔钱从公司账户付给一个普通用户。后台点一下「打款」钱在几秒内进入用户零钱中间要走的是微信支付的企业付款到零钱现在官方叫商家转账到零钱接口而不是普通的下单支付。这两者最大的区别在于下单是收钱转账是付钱付钱那条链路必须带商户证书签名错一个字、证书少一个字节都会直接返回FAIL。这个 C# Demo 覆盖了三条链路微信支付统一下单JSAPI / Native、企业付款到个人零钱、企业付款到银行卡用最原始的 XML 报文加 MD5/HMAC-SHA256 签名手搓了一遍。它适合两类人一是刚接手「提现」「返佣」需求、需要一份能对照着改的骨架的后端二是想搞清楚微信支付 v2 那套签名规则到底怎么算、证书怎么挂的开发者。代码不长但每一段都踩在真实的坑上。2. 项目结构与技术选型三层骨架撑起一个能跑的支付 Demo2.1 目录结构把「能跑的 Demo」拆成三层很多支付 Demo 的问题是把所有东西塞进一个Program.cs跑起来是能跑改起来就是灾难。这个项目的做法是按职责切成三个工程业务层和协议层彻底分开。WeChatPayDemo/ ├─ src/ │ ├─ WeChatPay.Demo.Api/ # ASP.NET Core Web API对外暴露下单/转账/回调接口 │ │ ├─ Controllers/PayController.cs │ │ ├─ Controllers/TransferController.cs │ │ ├─ Program.cs │ │ └─ appsettings.json │ ├─ WeChatPay.Core/ # 与业务无关的支付能力可被任何项目引用 │ │ ├─ Options/WeChatPayOptions.cs │ │ ├─ Security/SignHelper.cs │ │ ├─ Security/CertificateProvider.cs │ │ ├─ Protocol/XmlHelper.cs │ │ ├─ Protocol/WeChatPayClient.cs │ │ └─ Models/UnifiedOrderRequest.cs │ └─ WeChatPay.Demo.Console/ # 控制台工程改完代码随手跑一笔不用起 Web ├─ certs/ # apiclient_cert.p12 等.gitignore 里必须排除 └─ tests/WeChatPay.Core.Tests/ # 签名用例拿官方文档给的示例串做断言WeChatPay.Core是这个项目的核心价值所在。里面没有一行业务代码全是「怎么把一个字典变成签名串」「怎么把一个字典变成 XML」「怎么用证书建一个 HttpClient」这类原子能力。业务层拿到它之后只需要负责组装参数、落库、判断结果。控制台工程看着多余实际调试时最省事改完SignHelperdotnet run一下就能看到签名串对不对不用走一遍完整的 HTTP 链路。certs/目录单独拎出来是有意的。证书文件和代码混在一起很容易在git add .的时候被提交上去一旦进了仓库历史删都删不干净血泪经验。2.2 技术选型为什么是 HttpClient 加自签工具类而不是上官方 SDK项目跑在 .NET 6 / .NET 8 上用到的全是框架自带的东西没有引第三方支付 SDK也没有引 JSON 库——因为 v2 接口的报文本来就是 XML。HttpClient所有请求走HttpClient转账类接口需要挂客户端证书所以用的是HttpClientHandler.ClientCertificates.Add()这条路子。这里有个前提一个HttpClient实例只挂一个证书多商户场景必须按商户号缓存实例不能共用一个静态单例。X509Certificate2加载apiclient_cert.p12密码就是商户号不是 API 密钥很多人第一次就填错。System.Xml.LinqXML 的组装和解析都用XElement不手拼字符串。手拼最容易在desc字段里带个或就炸掉。IOptions 配置模式商户参数统一走配置注入代码里不出现任何硬编码的 appid 和密钥。选择不用官方 SDK 的理由很直接v2 那套接口本质就是「表单参数 签名 XML」自己封一层出问题时能一眼看到发出去的原始报文长什么样。SDK 把报文藏在里面调试的时候反而像对着一个黑匣子。等业务稳定、需要接 v3 的时候再考虑换 SDK 也不迟。提示如果目标框架是 .NET Framework 4.xHttpClientHandler和X509Certificate2的用法基本一致但Convert.ToHexString这类 .NET 5 的 API 要换成BitConverter.ToString(bytes).Replace(-, )。2.3 配置与密钥证书、商户号、API 密钥分别放哪配置项集中在一个强类型类里字段名跟微信文档保持一致避免看代码时来回对译。public class WeChatPayOptions { public const string SectionName WeChatPay; public string AppId { get; set; } default!; // 公众号/小程序 appid public string MchId { get; set; } default!; // 商户号同时是 p12 证书密码 public string ApiKey { get; set; } default!; // APIv2 密钥32 位 public string CertPath { get; set; } default!; // apiclient_cert.p12 相对/绝对路径 public string NotifyUrl { get; set; } default!; // 必须公网可访问 public string ServerIp { get; set; } default!; // 服务器出口 IP不要填 127.0.0.1 }对应的appsettings.json长这样。注意ApiKey只放占位符真实值走环境变量或者部署平台的密钥管理别跟着代码一起进仓库。{ WeChatPay: { AppId: wx0000000000000000, MchId: 1900000000, ApiKey: , CertPath: certs/apiclient_cert.p12, NotifyUrl: https://your-domain.com/api/pay/notify, ServerIp: 203.0.113.10 } }注册的时候顺手把校验做掉配置缺项直接启动失败比跑到线上第一笔转账才发现ApiKey是空字符串要好得多。builder.Services.AddOptionsWeChatPayOptions() .Bind(builder.Configuration.GetSection(WeChatPayOptions.SectionName)) .Validate(o !string.IsNullOrWhiteSpace(o.AppId) !string.IsNullOrWhiteSpace(o.MchId) o.ApiKey?.Length 32, 微信支付配置不完整请检查 AppId / MchId / ApiKey) .ValidateOnStart();ApiKey长度固定 32 位这个校验能拦住一大半「签名错误」。因为密钥末尾多一个空格、或者复制的时候被换行截断现象都表现为签名不通过排查起来极其浪费时间。3. 核心链路拆解一笔企业付款到零钱从拼参数到拿回执的全过程3.1 签名所有接口的第一道门槛v2 接口的签名规则本身不复杂难在细节参与签名的字段必须是非空值必须排除 sign 字段本身必须按字段名 ASCII 升序排列最后拼上keyAPI密钥再做 MD5 或 HMAC-SHA256。任何一条不满足服务端算出来的就是另一个值。public static class SignHelper { /// summary /// 微信支付 v2 签名非空字段 排除 sign 字段名 ASCII 升序 末尾拼 key /// /summary public static string Build(IDictionarystring, string dict, string apiKey, string signType MD5) { var sb new StringBuilder(); foreach (var kv in dict.Where(p p.Key ! sign !string.IsNullOrWhiteSpace(p.Value)) .OrderBy(p p.Key, StringComparer.Ordinal)) { sb.Append(kv.Key).Append().Append(kv.Value).Append(); } sb.Append(key).Append(apiKey); // key 参与拼接但不参与排序 var raw sb.ToString(); if (signType HMAC-SHA256) { using var hmac new HMACSHA256(Encoding.UTF8.GetBytes(apiKey)); return Convert.ToHexString(hmac.ComputeHash(Encoding.UTF8.GetBytes(raw))).ToUpperInvariant(); } using var md5 MD5.Create(); return Convert.ToHexString(md5.ComputeHash(Encoding.UTF8.GetBytes(raw))).ToUpperInvariant(); } }几个参数和实现细节值得单独说。StringComparer.Ordinal是必须的不能用默认的OrderBy(p p.Key)因为默认比较器受当前区域性影响在某些环境里_和字母的相对顺序会不一样本地跑通、服务器报签名错误十有八九是这里。MD5 结果统一转大写HMAC-SHA256 在 v2 里也要求大写这两处微信文档写得不显眼但服务端是严格比对的。total_fee、amount这类金额字段在签名前就已经是字符串形态的整数分不要在这一层做任何格式化1000.00和1000算出来的签名不同。注意签名串里如果出现中文比如body字段编码必须是 UTF-8。用Encoding.Default在 Windows 上可能侥幸跑通换到 Linux 容器里就是另一回事。3.2 统一下单先把订单号、金额和回调地址组织好下单是所有支付链路的起点。这个 Demo 里统一下单走的是 JSAPI返回prepay_id之后前端还要再做一次签名才能调起收银台。public async TaskUnifiedOrderResult UnifiedOrderAsync(UnifiedOrderRequest req) { var dict new Dictionarystring, string { [appid] _opt.AppId, [mch_id] _opt.MchId, [nonce_str] Guid.NewGuid().ToString(N), // 32 位随机串每次都要换 [body] req.Body, // 展示在用户账单里别写内部代号 [out_trade_no] req.OutTradeNo, // 商户侧唯一退款和对账都靠它 [total_fee] req.TotalFeeFen.ToString(), // 单位是分不是元 [spbill_create_ip] req.ClientIp, [notify_url] _opt.NotifyUrl, [trade_type] JSAPI, [openid] req.OpenId, [sign_type] MD5 }; dict[sign] SignHelper.Build(dict, _opt.ApiKey); var xml XmlHelper.ToXml(dict); using var content new StringContent(xml, Encoding.UTF8, text/xml); var raw await _http.PostAsync(https://api.mch.weixin.qq.com/pay/unifiedorder, content) .Result.Content.ReadAsStringAsync(); var result XmlHelper.ParseUnifiedOrderResult(raw); if (result.ReturnCode ! SUCCESS || result.ResultCode ! SUCCESS) throw new WeChatPayException(result.ReturnMsg ?? result.ErrCodeDes, raw); return result; }参数里有三处容易出错。out_trade_no是幂等的锚点同一笔业务必须复用同一个单号重复下单微信会直接返回「订单号重复」notify_url必须是公网能访问的 https 地址本地开发想收回调只能靠内网穿透工具临时映射total_fee用int存储别用decimal微信只认整数分。拿到prepay_id之后前端还要再签一次名这次用的是timeStamp、nonceStr、packageprepay_idxxx、signType四个字段加同一个 API 密钥规则和上面完全一样可以直接复用SignHelper.Build。public JsApiPayParams BuildJsApiParams(string prepayId) { var dict new Dictionarystring, string { [appId] _opt.AppId, [timeStamp] DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString(), [nonceStr] Guid.NewGuid().ToString(N), [package] $prepay_id{prepayId}, [signType] MD5 }; dict[paySign] SignHelper.Build(dict, _opt.ApiKey); return new JsApiPayParams(dict); }3.3 企业付款到零钱带证书的那一条 POST这条接口和下单最大的差别是必须带客户端证书走双向 TLS。请求地址是mmpaymkttransfers/promotion/transfers字段名也和下单不一样叫mch_appid和mchid不是appid和mch_id。直接复制下单的字典过来改一定会报参数错误。public static HttpClient CreateClient(string p12Path, string mchId) { // 密码是商户号不是 API 密钥 var cert new X509Certificate2( p12Path, mchId, X509KeyStorageFlags.MachineKeySet | X509KeyStorageFlags.PersistKeySet | X509KeyStorageFlags.Exportable); var handler new HttpClientHandler(); handler.ClientCertificates.Add(cert); return new HttpClient(handler) { Timeout TimeSpan.FromSeconds(15) }; }X509KeyStorageFlags这三个标志是踩坑踩出来的。MachineKeySet让私钥落在机器级存储里容器环境下能避免用户级存储不可写的问题PersistKeySet保证多次加载同一个证书时私钥不丢Exportable在 Linux 上做 p12 重新导出时是必需的。少一个表现可能是CryptographicException也可能是「握手成功但服务端说没有证书」。转账本身的方法就清晰了参数组装完直接 POSTpublic async TaskTransferResult TransferAsync(TransferRequest req) { using var client CertificateProvider.CreateClient(_opt.CertPath, _opt.MchId); var dict new Dictionarystring, string { [mch_appid] _opt.AppId, // 注意是 mch_appid [mchid] _opt.MchId, // 注意是 mchid [nonce_str] Guid.NewGuid().ToString(N), [partner_trade_no] req.PartnerTradeNo, // 商户侧转账单号必须唯一 [openid] req.OpenId, // 必须与 mch_appid 同源 [check_name] req.CheckName, // NO_CHECK / OPTION_CHECK / FORCE_CHECK [re_user_name] req.RealName, // check_name 非 NO_CHECK 时必填 [amount] req.AmountFen.ToString(), // 单位分 [desc] req.Desc, // 展示在用户零钱明细写清楚用途 [spbill_create_ip] _opt.ServerIp }; dict[sign] SignHelper.Build(dict, _opt.ApiKey); var xml XmlHelper.ToXml(dict); using var content new StringContent(xml, Encoding.UTF8, text/xml); var resp await client.PostAsync( https://api.mch.weixin.qq.com/mmpaymkttransfers/promotion/transfers, content); var raw await resp.Content.ReadAsStringAsync(); var result XmlHelper.ParseTransferResult(raw); if (result.ResultCode ! SUCCESS) throw new WeChatPayException(${result.ErrCode}:{result.ErrCodeDes}, raw); return result; // 含 payment_no、payment_time落库留存 }check_name的取值直接决定风控强度NO_CHECK不校验实名单笔和单日额度最低FORCE_CHECK强校验必须传re_user_name且与用户实名一致OPTION_CHECK介于两者之间实名对不上会失败、不传则跳过。业务上如果是给陌生人打佣金建议FORCE_CHECK虽然麻烦但能挡住一批脏 openid。partner_trade_no是这张转账单的主键重复提交同一单号微信会返回失败而不是重复付款这一点比下单接口更严格也是幂等的天然屏障。3.4 回调与结果判读怎么确认钱真的到了企业付款到零钱这个接口成功返回里的result_codeSUCCESS只代表受理成功钱到没到账要以查询接口或用户零钱明细为准。这也是很多人第一次接的时候会误判的地方。回调本身是 XML POST 到notify_url处理逻辑分三步验签、幂等、返回规定的 XML。[HttpPost(/api/pay/notify)] public async TaskIActionResult Notify() { using var reader new StreamReader(Request.Body, Encoding.UTF8); var xml await reader.ReadToEndAsync(); var data XmlHelper.ToDictionary(xml); // 1) 验签用收到的全部字段重算一次 var calc SignHelper.Build(data, _opt.ApiKey); if (!string.Equals(calc, data.GetValueOrDefault(sign), StringComparison.OrdinalIgnoreCase)) return Content(XmlHelper.ToXml(Fail(签名校验失败)), text/xml); if (data.GetValueOrDefault(return_code) SUCCESS data.GetValueOrDefault(result_code) SUCCESS) { // 2) 幂等out_trade_no 上建唯一索引插入失败说明已处理过 await _orderService.MarkPaidAsync(data[out_trade_no], data[transaction_id]); } // 3) 必须返回这个格式否则微信会按 15s/15s/30s/3m/10m 的节奏重试 return Content(XmlHelper.ToXml(new Dictionarystring, string { [return_code] SUCCESS, [return_msg] OK }), text/xml); }return_code和result_code是两层含义前者代表通信层面是否成功后者代表业务层面是否成功。只有当两个都是SUCCESS时才是真正的支付成功。处理完业务后无论成功失败都要返回SUCCESS否则微信会持续重推把日志刷满。如果转账结果不确定比如网络超时走查询接口mmpaymkttransfers/gettransferinfo参数是appid、mch_id、partner_trade_no、nonce_str加签名同样要带证书。转账类业务里这个查询接口的使用频率其实比转账接口本身还高。4. 本地跑通从改配置到第一笔 0.01 元转账4.1 环境与前置条件代码之外的部分更难先把话说在前面这个 Demo 能跑起来一半靠代码一半靠商户平台那边的开通状态。以下条件缺一个代码再对也是白跑。已认证的服务号或小程序拿到AppId并且与商户号完成关联。商户平台已开通「企业付款到零钱」新版叫商家转账产品未开通时接口会直接返回无权限。已设置 32 位 APIv2 密钥注意设置后不可查看只能重置。已下载apiclient_cert.p12证书密码是商户号。商户平台里配置了服务器出口 IP 白名单spbill_create_ip要和它一致。本地开发想收回调notify_url需要一个公网可达的地址。开发环境用 .NET 8 SDK 就够还原和启动两条命令dotnet restore dotnet run --project src/WeChatPay.Demo.Api控制台工程更适合验证签名这类纯逻辑单元dotnet run --project src/WeChatPay.Demo.Console -- --sign-test4.2 证书与参数填写最容易翻车的一步把apiclient_cert.p12放进certs/目录CertPath指向它MchId填进去当密码。如果部署目标是 Linux 容器.NET加载 p12 有时会因为 OpenSSL 版本或证书里带的额外属性失败稳妥的做法是转成 PEM 再重新打包# p12 拆成证书和私钥密码是商户号 openssl pkcs12 -in apiclient_cert.p12 -clcerts -nokeys -out apiclient_cert.pem -passin pass:1900000000 openssl pkcs12 -in apiclient_cert.p12 -clcerts -nocerts -out apiclient_key.pem -passin pass:1900000000 # 重新导出成兼容性更好的 p12 openssl pkcs12 -export -in apiclient_cert.pem -inkey apiclient_key.pem \ -out apiclient_all.p12 -passout pass:1900000000加载的时候换成CreateFromPemFile再导出这条路在 Linux 上最稳var pem X509Certificate2.CreateFromPemFile(certPemPath, keyPemPath); var cert new X509Certificate2(pem.Export(X509ContentType.Pfx), mchId, X509KeyStorageFlags.MachineKeySet | X509KeyStorageFlags.Exportable);注意certs/目录必须写进.gitignore。证书一旦提交进仓库即使后面删除历史和 fork 里都还在。4.3 发起请求与读日志断点打在什么位置接口启动后先跑一笔转账。金额用 1 分就行既能验证链路又能控制成本。curl -X POST http://localhost:5000/api/transfer \ -H Content-Type: application/json \ -d {openId:o00000000000000000000000000000,realName:用户实名,amountFen:1,desc:佣金提现测试}调试阶段最有效的手段是在三个位置打日志签名前排好序的字典、发出去之前的完整 XML、收到的原始响应 XML。这三个东西一摆出来问题基本能定位到具体字段。日志里openid要脱敏只保留前 6 位和后 4 位ApiKey绝对不能出现。_logger.LogDebug(签名原文: {Raw}, raw); _logger.LogDebug(请求报文: {Xml}, xml); _logger.LogDebug(响应报文: {Xml}, responseXml);如果返回FAIL先看return_msg如果是SUCCESS但result_codeFAIL看err_code和err_code_des。这两组字段的含义完全不同混着看会走很多弯路。4.4 小额验证与对账确认钱真的到账1 分钱的转账提交成功后回到商户平台的交易记录里查partner_trade_no状态应该是「已付款」同时让对应用户打开零钱明细desc字段内容会原样显示在那里这也是为什么desc不要写内部订单号或者测试字样。接着调一次查询接口做闭环验证var query new Dictionarystring, string { [appid] _opt.AppId, // 查询接口这里又变回 appid / mch_id [mch_id] _opt.MchId, [partner_trade_no] partnerTradeNo, [nonce_str] Guid.NewGuid().ToString(N) }; query[sign] SignHelper.Build(query, _opt.ApiKey);注意查询接口的字段名是appid/mch_id和转账接口的mch_appid/mchid正好对调。同一个项目里两套命名写的时候很容易复制错建议在模型类上直接写注释标明来源接口。对账这块正式环境建议每天跑一次「本地转账记录 LEFT JOIN 微信交易记录」的比对找出本地标记成功但微信侧没成功的孤儿单以及微信侧成功但本地没登记的回调丢失单。5. 避坑与排查五条让我加过班的真实报错5.1 签名错误本地通过、服务器全挂现象很典型本地调接口一切正常发到测试环境之后所有请求统一返回return_codeFAIL/return_codereturn_msg签名错误/return_msg代码一个字没改。原因基本锁定在三个地方。一是配置读取的密钥末尾带了空格或换行Trim()能解决二是排序用了默认比较器跨区域性环境下_和字母顺序不一致三是某些字段在本地是 null 被跳过到了线上被某段逻辑赋成了空字符串空字符串在IsNullOrWhiteSpace里会被过滤但如果代码里判断的是! null就会参与签名多出一段attach。解决办法是固定一条排查路径把参与签名的原始串打印出来逐字符和官方文档给出的示例串比对而不是猜。同时配置类里对ApiKey做长度校验和Trim()处理从源头堵住。5.2 证书加载失败Linux 容器里的 p12 兼容问题现象是X509Certificate2构造时抛CryptographicException: The system cannot find the file specified或者更隐晦的unable to load certificate路径明明是对的。原因有两个层面。一是 p12 密码填错了很多人第一次填成了 API 密钥而正确的密码是商户号二是 .NET 在 Linux 上通过 OpenSSL 解析 p12旧版 OpenSSL 对某些加密算法和自定义属性支持不好Windows 能读的文件换到容器里就读不出来。另外容器镜像里如果没装ca-certificates握手阶段也会失败。解决方案分两步先用openssl pkcs12 -info在命令行确认这个 p12 能不能被当前系统读出来读不出来就按 4.2 节的流程转成 PEM 再重新导出容器基础镜像里显式安装ca-certificates和libssl相关包别指望 slim 镜像自带。5.3 金额与 openid报错信息最会骗人的两处现象之一是接口返回PARAM_ERROR反复检查参数名都对现象之二是接口返回SUCCESS但用户说没收到钱现象之三是直接OPENID_ERROR。原因分别是金额字段的单位是分业务层如果传的是decimal元再强转int9.99m会变成9少付了 99 分虽然不报错但金额对不上openid是有归属的公众号的 openid 和 小程序的 openid 不是同一个用 A 应用的 openid 去调 B 应用的转账接口服务端校验不通过。解决办法是把金额在领域模型入口就转成int分全链路不出现浮点数openid、appid一起存进用户表转账时校验二者的appid是否和配置里的一致不一致直接抛业务异常而不是发给微信。5.4 回调重复与丢单没有幂等表的代价现象是用户零钱到账了但本地订单状态一直停在「处理中」或者更糟同一笔回调进来三次账户余额被加了三遍。原因在回调处理端。订单状态没更新通常是处理逻辑抛了异常没被捕获或者返回体不是微信要求的 XML 格式微信认为没收到确认就一直重推。余额被重复加是因为处理逻辑没有幂等控制回调来一次就执行一次。解决办法是在out_trade_no或partner_trade_no上建唯一索引处理前先做一次插入尝试插入失败说明这单已经处理过直接返回成功业务处理放到事务里失败回滚返回非SUCCESS让微信重推而不是吞掉异常返回成功。5.5 IP 白名单与 spbill_create_ip最不像 bug 的 bug现象是接口时而成功时而失败或者直接返回无权限类错误日志里看不出任何规律。原因是spbill_create_ip填了这个字段但填的是127.0.0.1或者服务器做了多出口 NAT实际出口 IP 和商户平台白名单里配的那个不一致。微信侧对来源 IP 做校验多台机器负载均衡时只有部分请求会命中白名单。解决办法是把ServerIp做成配置项值填服务器的真实出口 IP从部署环境注入而不是硬编码多出口的场景要和运维确认稳定的出口地址或者把所有可能出口都加进白名单。6. 二次开发把 Demo 收成能上生产的一层封装Demo 到生产之间隔着三件事接口抽象、幂等落库、版本迁移。6.1 抽接口与多商户路由不要把WeChatPayClient直接注入到 Controller 里。抽一个业务语义的接口支付细节留在实现类public interface ITransferService { TaskTransferResult TransferToWalletAsync(string bizNo, string openId, int amountFen, string desc); } // 多商户按 key 取不同的 HttpClient 实例证书不能共用 public class WeChatPayClientFactory { private readonly ConcurrentDictionarystring, HttpClient _cache new(); public HttpClient Get(string mchId, string certPath) _cache.GetOrAdd(mchId, _ CertificateProvider.CreateClient(certPath, mchId)); }HttpClient按商户号缓存是因为一个实例只能挂一张证书。这一点在做 SaaS 多租户时特别关键早期用一个静态HttpClient到处传后面加第二个商户就得推倒重来。6.2 幂等表、重试与对账转账接口天然要求幂等partner_trade_no就是你的业务单号落库时建唯一索引。重试策略要区分错误码SYSTEMERROR、网络超时可以重试PARAM_ERROR、AMOUNT_LIMIT重试多少次都没用。重试前先调一次gettransferinfo查询确认上一笔到底是什么状态再决定要不要重发。对账任务每天跑一次比对本地转账表和微信交易记录把「本地成功、微信失败」的单子标出来人工介入。这块逻辑不复杂但它是唯一能在出事后把账扳平的手段。6.3 v2 到 v3 的迁移路线企业付款到零钱这条 v2 接口新商户号已经很难申请到权限了对应的替代品是 v3 的「商家转账到零钱」。差异不小报文从 XML 换成 JSON签名从 MD5 换成SHA256-RSA2048用商户私钥签名用平台证书验签请求头要带Authorization: WECHATPAY2-SHA256-RSA2048 ...证书体系也换成了商户 API 证书加平台证书两套。迁移不用推倒重来。把SignHelper和WeChatPayClient抽象成接口v2 和 v3 各写一个实现业务层依赖接口配置里加一个ApiVersion开关灰度的时候按商户号切。这样新老商户能并行跑一段时间比一次性全量切换安全得多。从那以后我每次接支付相关需求都是先把幂等表和回调日志这两件事落在业务代码之前再去写转账逻辑——钱这条链路上任何「应该不会重复」的假设最后都会被打脸。希望帮到你。本文还有配套的精品资源点击获取
