简介这是一份面向C#开发者的微信支付集成DEMO资源覆盖JSAPI支付、刷卡与扫码支付、企业付款到个人、企业付款到零钱、订单退款与查询、账单下载等核心接口调用流程配有基于WxPayAPI的完整示例工程便于直接对照调试或移植到实际项目中。压缩包共93个文件以47个cs源码文件、13个aspx页面、8个dll类库和5个config配置为主辅以js、xml、pdb等辅助文件整体约2.13MB结构清晰适合从零接入微信支付或需要快速验证企业转账场景的初中级开发者。已有1575人学习下载。借助工程中的SDK封装与代码示例可以省去通读官方文档和反复调试签名、回调、证书配置的弯路快速理清支付、退款、对账等模块的调用关系与参数要求。1. 微信企业付款到零钱一个被低估的C#实战场景在C#项目里接微信企业付款到零钱最反直觉的一件事是流程并不在你调用接口返回成功时结束。接口返回SUCCESS只代表微信受理了这笔转账真正到账可能还要再等几秒到几分钟甚至可能因为风控被驳回。这份C#代码DEMO把“微信支付、微信企业支付到个人、微信企业付款到零钱”的完整请求链路串了起来从加载商户证书、拼装参数、MD5签名到调用/mmpaymkttransfers/promotion/transfers接口并解析结果开箱即跑。它适合两类人一类是做电商、分销返利系统需要自动给用户余额提现到微信零钱的开发者另一类是刚接手支付模块被证书和签名整得头疼的.NET工程师。下面我会从项目结构拆到每个核心方法最后聊怎么改造成生产级。2. 技术选型与项目结构证书、API版本与目录总览2.1 为什么选C#HttpClient与客户端证书的天然契合很多人提到微信支付就默认用PHP或Java但C#做企业付款到零钱其实非常顺手。微信这个老版接口要求双向HTTPS认证也就是除了常规的服务器证书客户端这边还得带上商户自己的apiclient_cert.p12证书文件。在.NET里HttpClientHandler直接支持挂载X509Certificate2几行代码就能完成双向认证不像某些语言还需要额外拼装JKS或PEM格式转换。我建议优先用.NET 6或.NET 8来跑这个DEMO底层HttpClient对TLS协议的处理更完善跨平台部署时也不会被Windows证书存储卡住。如果你还在用.NET Framework 4.x代码基本能平移只是HttpClientHandler换成WebRequestHandler证书加载方式完全一致。技术栈上这个DEMO没有引入重量级框架就是ASP.NET Core Web API 原生HttpClient 官方XML接口协议。选ASP.NET Core而不是控制台是因为大多数业务场景是把付款能力嵌在现有Web服务里Controller里的接口可以直接被前端或定时任务调用。如果你只想跑个命令行测试把TransferService的Main调用提出来就能独立运行。2.2 项目目录结构与职责拿到源码包先看整体结构不要急着跑。DEMO目录按“对外接口 → 业务服务 → 工具类”做了三层拆分看一眼就能知道每个文件是该改的还是不该动的WxPayDemo/ ├── Controllers/ │ └── PayController.cs # 对外HTTP入口接收付款请求 ├── Services/ │ └── WxTransferService.cs # 核心业务逻辑签名、调用、解析 ├── Models/ │ ├── WxPayConfig.cs # 配置实体AppId、商户号、证书路径等 │ ├── TransferRequest.cs # 付款请求参数模型 │ └── TransferResult.cs # 付款响应结果模型 ├── Utils/ │ ├── WxSign.cs # 签名工具类MD5字典序签名 │ └── XmlHelper.cs # XML与实体互转 ├── wwwroot/ │ └── cert/ │ └── apiclient_cert.p12 # 微信支付商户证书你的要替换掉 └── appsettings.json # 配置文件存放敏感参数PayController是最外层只负责接收HTTP参数并调用WxTransferServiceWxTransferService承担了所有微信交互逻辑包括签名、HTTP请求、异常处理Models里三个实体类负责数据承载。WxSign和XmlHelper是纯静态工具类不依赖业务状态可以在其他项目里直接复用。这个结构的核心思想是“Controller不碰微信协议”。我见过不少DEMO把签名和请求逻辑全写在Controller里看起来简单但你要加一个查单接口或者对账任务时就得复制粘贴一整块代码。拆开之后新增接口只需要在Service里加方法Controller保持干净。2.3 配置项证书、商户号、AppID怎么填配置集中在appsettings.json里一共五个必填项缺一个就跑不通配置项对应字段从哪里拿备注WxPay:AppIdmch_appid商户平台-账号中心-应用ID必须与openid所属应用一致否则报错WxPay:MchIdmchid商户平台-账号中心-商户号10位纯数字WxPay:ApiKeykey签名密钥商户平台-账户中心-API安全-APIv2密钥32位自己设置的WxPay:CertPath客户端证书文件商户平台-API安全-API证书-下载证书p12文件路径WxPay:CertPasswordp12证书密码下载证书时设置固定为商户号默认密码就是MchId别改这里先插一句踩过多年的坑ApiKey不是证书密码证书密码固定是商户号。很多人把APIv2密钥当成证书密码输进去导致证书加载时直接抛CryptographicException白白浪费半天。另外新版商家转账用的是APIv3密钥和apiclient_key.pem不能用错后面第6章会专门讲升级。appsettings.json里写好后配置类注入方式如下public class WxPayConfig { public string AppId { get; set; } public string MchId { get; set; } public string ApiKey { get; set; } public string CertPath { get; set; } public string CertPassword { get; set; } }在Program.cs里注册为单例之后控制器和Service都能直接注入builder.Services.ConfigureWxPayConfig(builder.Configuration.GetSection(WxPay)); builder.Services.AddSingletonWxTransferService();注意证书路径尽量用绝对路径或者Path.Combine(AppDomain.CurrentDomain.BaseDirectory, wwwroot, cert, apiclient_cert.p12)避免部署到IIS后相对路径飘掉。这个问题在避坑章节会再展开。3. 核心模块拆解一个付款请求从签名到返回的完整链路3.1 参数组装与签名算法企业付款到零钱的老版接口使用MD5签名签名规则是“按参数名ASCII码字典序排序 → 拼接keyvalue→ 末尾拼上API密钥 → MD5 → 转大写”。这个规则看起来简单但排序漏掉任何一位参数都会导致签名不一致。DEMO里用SortedDictionary来保证字典序避免手写排序出错。public static string BuildSign(SortedDictionarystring, string dict, string apiKey) { // 拼接待签名字符串k1v1k2v2...keyApiKey var sb new StringBuilder(); foreach (var kv in dict) { if (!string.IsNullOrEmpty(kv.Value) kv.Key ! sign) { sb.Append(${kv.Key}{kv.Value}); } } sb.Append(key apiKey); // MD5加密并转大写 using var md5 MD5.Create(); byte[] bytes md5.ComputeHash(Encoding.UTF8.GetBytes(sb.ToString())); var result new StringBuilder(); foreach (byte b in bytes) { result.Append(b.ToString(X2)); // 大写十六进制 } return result.ToString(); }逻辑说明SortedDictionary会自动按键名的ASCII码升序排列所以字典里键的顺序不需要你操心。拼接时跳过空值和sign本身这是微信官方要求的“值为空不参与签名”。最后一行的key拼的是APIv2密钥不是AppSecret更不是证书密码。整个签名串的原文建议在DEBUG日志里完整打出来排查签名问题时能直接对照。接下来组装业务参数。企业付款到零钱接口必传字段包括mch_appid、mchid、partner_trade_no、openid、check_name、amount、desc、spbill_create_ip、nonce_str。其中check_name有三种取值NO_CHECK不校验姓名、FORCE_CHECK强制校验、OPTION_CHECK商户传入姓名则校验。做用户提现到零钱场景大多数选择NO_CHECK因为用户本身就在你系统里实名过再传姓名会多一道校验失败的风险。public async TaskTransferResult TransferToWxWallet(TransferRequest req) { // 1. 构造签名前的参数字典 var dict new SortedDictionarystring, string { { mch_appid, _config.AppId }, { mchid, _config.MchId }, { partner_trade_no, req.PartnerTradeNo }, // 商户订单号唯一 { openid, req.OpenId }, // 用户openid { check_name, req.CheckName }, // NO_CHECK / FORCE_CHECK { amount, req.Amount.ToString() }, // 单位分最低30 { desc, req.Desc }, // 付款描述必填 { spbill_create_ip, req.SpbillCreateIp }, // 调用接口的IP { nonce_str, Guid.NewGuid().ToString(N).Substring(0, 16) } }; // 2. 计算签名并加入参数 string sign WxSign.BuildSign(dict, _config.ApiKey); dict.Add(sign, sign); // 3. 转XML准备POST string xml XmlHelper.MapToXml(dict); // ... 后续请求代码省略见3.2 }逻辑说明partner_trade_no是商户侧生成的转账单号同一商户号下必须唯一用来做幂等和查单关键凭证。建议用yyyyMMddHHmmss加随机数或数据库自增ID拼成不要用Guid太长避免超长。amount单位是「分」如果你业务端拿的是元记得(int)Math.Round(yuan * 100)这个转换在避坑章节会专门讲。3.2 加载客户端证书并调用接口微信老版企业付款接口要求HTTPS双向认证你的服务器必须带上商户证书证明身份。HttpClientHandler的ClientCertificates集合就是干这个的。这里的重点是证书加载方式直接传cert.Password可能在某些环境中失败推荐先读byte[]再从字节数组加载绕开文件锁和权限问题。private async Taskstring PostXmlAsync(string url, string xml) { // 从字节数组加载证书避免IIS文件锁或权限不足 byte[] certBytes File.ReadAllBytes(_config.CertPath); var cert new X509Certificate2(certBytes, _config.CertPassword, X509KeyStorageFlags.MachineKeySet | X509KeyStorageFlags.PersistKeySet); var handler new HttpClientHandler(); handler.ClientCertificates.Add(cert); handler.ClientCertificateOptions ClientCertificateOption.Manual; using var client new HttpClient(handler); client.Timeout TimeSpan.FromSeconds(10); var content new StringContent(xml, Encoding.UTF8, application/xml); var response await client.PostAsync(url, content); string result await response.Content.ReadAsStringAsync(); // 日志留底请求与响应原文排查必用 _logger.LogInformation(WxTransfer Request: {url} {xml}, url, xml); _logger.LogInformation(WxTransfer Response: {result}, result); return result; }逻辑说明X509KeyStorageFlags.MachineKeySet和PersistKeySet这两个标志在Linux容器里尤其重要不加的话可能在容器重启后报“证书私钥丢失”的错。如果你在Windows IIS上跑MachineKeySet能让私钥用机器级密钥容器避免站点池用户权限不够访问用户级存储。调用地址是https://api.mch.weixin.qq.com/mmpaymkttransfers/promotion/transfers老版新版V3地址不同后面第6章会列出来。HttpClient超时建议设10秒以上因为微信风控审核耗时可能超过默认的5秒超时短了容易误判接口没响应。3.3 响应解析与错误码处理微信返回的是XML字符串先用XDocument解析出return_code和result_code两层的状态。return_code表示请求是否被微信受理result_code表示具体业务是否成功。这两个必须都判断为SUCCESS才算成功只判断return_code会漏掉业务失败。public TransferResult ParseTransferResponse(string xml) { var result new TransferResult(); var doc XDocument.Parse(xml); result.ReturnCode doc.Root.Element(return_code)?.Value; result.ReturnMsg doc.Root.Element(return_msg)?.Value; result.ResultCode doc.Root.Element(result_code)?.Value; result.ErrCode doc.Root.Element(err_code)?.Value; result.ErrCodeDes doc.Root.Element(err_code_des)?.Value; // 只看return_code不行必须看result_code if (result.ReturnCode SUCCESS result.ResultCode SUCCESS) { result.PartnerTradeNo doc.Root.Element(partner_trade_no)?.Value; result.PaymentNo doc.Root.Element(payment_no)?.Value; // 微信付款单号 result.PaymentTime doc.Root.Element(payment_time)?.Value; // 格式yyyy-MM-dd HH:mm:ss result.IsSuccess true; } else { result.IsSuccess false; // 常见错误码NO_AUTH / AMOUNT_LIMIT / FREQ_LIMIT / NAME_MISMATCH } return result; }逻辑说明payment_no是微信侧生成的单号一定要落库保存后续退款、查单或客服查询都需要它。payment_time是微信受理时间不是最终到账时间。接口返回成功后的状态流转建议设计成“付款中PENDING”等查单或回调确认后才改成“已到账SUCCESS”。错误码处理有个经验微信错误码保存在err_code描述在err_code_des出现NO_AUTH时别先怀疑代码多半是商户号没开通企业付款权限登录商户平台-产品中心检查一下。AMOUNT_LIMIT则是金额超过单笔上限或低于最低额FREQ_LIMIT是频率限制。这些错误码建议直接映射成你业务侧可理解的枚举而不是把err_code_des原文抛给前端。4. 避坑指南证书、签名与额度限制的五个雷区4.1 证书加载失败IIS下pfx文件读取权限现象本地控制台测试证书加载正常部署到IIS后抛CryptographicException: 系统找不到指定的文件或“拒绝访问”。原因IIS应用程序池账户默认DefaultAppPool对wwwroot/cert目录没有读取权限或者证书私钥无法写入机器密钥库。p12文件包含私钥加载时需要在磁盘上创建临时密钥文件没写权限就直接翻车。解决先说临时方案给wwwroot/cert目录加上IIS_IUSRS读取权限一劳永逸的做法是从byte[]加载证书代码见3.2把X509KeyStorageFlags设为MachineKeySet | PersistKeySet让私钥存到机器级仓库。从那以后我每部署一次支付服务都会强制跑一遍“证书读取冒烟测试”直接调一个只加载证书不调微信的接口确认证书没问题再放流量。4.2 签名校验失败参数排序与大小写的坑现象接口返回签名错误或参数格式错误日志里签名串看起来也没毛病。原因最常见的有三种。第一SortedDictionary排序后漏了参数比如mch_appid写成了appid字段名对不上微信文档第二MD5结果没转大写微信要求大写第三签名串末尾拼接的key后面跟的是APIv2密钥有人误用了APIv3密钥或AppSecret。解决在BuildSign方法里把完整签名原文含key打到日志然后和微信官方签名校验工具逐字符对比。我的习惯是写一个SignDebug开关只开在测试环境线上不打印完整签名串避免密钥泄漏。4.3 openid不匹配AppID与商户号绑定关系现象请求成功但微信返回openid与商户号不匹配或appid和openid不匹配。原因用户在小程序里登录获取的openid拿到公众号的AppId下去付款两个应用的主体不一致。老版企业付款接口的mch_appid必须是商户号绑定并认证通过的AppID且openid必须属于这个AppID。解决确认用户注册来源。如果系统里只保留了一种应用身份给付款接口传参前先校验openid对应的应用类型。可靠校验方式是付款前调一次微信cgi-bin/user/info接口验证openid通过再组装付款参数。这也是防止“别人拿你商户号给任意openid付款”的安全底线。4.4 金额单位与最低限制0.01元与0.30元的距离现象接口返回金额不合法或者自己本地测试传了1元却报AMOUNT_LIMIT。原因企业付款到零钱接口的amount单位是分最低0.30元即30分单笔最高20000元即2000000分。把“1元”直接当整数传成1实际被微信理解为0.01元低于最低限制直接拒绝。解决统一在业务层定义一个“元转分”的公共方法public static int YuanToFen(decimal yuan) { return (int)Math.Round(yuan * 100, MidpointRounding.AwayFromZero); }注意别用Convert.ToInt32它默认四舍五入是银行家舍入法碰到0.015这类数值行为不一样。付款前加一层业务校验fen 30直接提示“最低转账0.30元”避免把微信错误码暴露给用户。我习惯在TransferRequest里给Amount加Range注解接口层先拦住非法请求。4.5 频率限制同一用户当日付款次数现象白天付款正常下午开始报FREQ_LIMIT描述类似“该用户今日付款次数超限”。原因微信对“同一openid当天从同一商户号收款”有次数限制老版企业付款接口在没有额外提额时通常同一用户每天不能超过几次。这个限制商户平台看不到只能被接口拒绝后才知道。解决有两种策略。第一从业务上合并提现订单比如用户当日多次小额提现后台合并成一次付款发起第二排队处理把付款请求写入消息表定时任务按用户维度串行消费遇到FREQ_LIMIT就顺延到下一时段。千万不要收到FREQ_LIMIT后立刻原参数重试大概率连续撞限还可能导致当日彻底不可用。5. 从DEMO到生产查单、幂等与对账设计5.1 付款状态查询老版接口没有回调怎么确认到账老版企业付款到零钱没有一个主动回调来通知“已到账”唯一的确认手段是主动查单。接口是/mmpaymkttransfers/gettransferinfo传商户订单号partner_trade_no就能查到该笔转账的状态。落地到生产环境建议做成定时任务每30秒扫一遍状态为“付款中”的订单调一次查单接口更新状态。public async TaskTransferResult QueryTransferAsync(string partnerTradeNo) { var dict new SortedDictionarystring, string { { appid, _config.AppId }, // 注意查单接口用appid不是mch_appid { mch_id, _config.MchId }, { partner_trade_no, partnerTradeNo }, { nonce_str, Guid.NewGuid().ToString(N).Substring(0, 16) } }; string sign WxSign.BuildSign(dict, _config.ApiKey); dict.Add(sign, sign); string xml XmlHelper.MapToXml(dict); string response await PostXmlAsync( https://api.mch.weixin.qq.com/mmpaymkttransfers/gettransferinfo, xml); // 判断status字段SUCCESS表示已到账 var doc XDocument.Parse(response); string status doc.Root.Element(status)?.Value; // SUCCESS: 转账成功; PROCESSING: 处理中; FAILED: 转账失败 return new TransferResult { IsSuccess status SUCCESS, Status status }; }逻辑说明查单接口的参数名是appid和mch_id和付款接口的mch_appid/mchid不一样直接复制付款参数会报“缺少参数”。响应里的status才是真正的到账状态SUCCESS表示钱已到用户零钱FAILED要结合reason字段看失败原因。5.2 幂等设计商户订单号与数据库唯一约束网速抖动、定时任务重复触发、前端按钮连点……任何一个生产场景都会让同一个付款请求被发两次。如果不对partner_trade_no做幂等用户会被重复扣款。数据库层面的设计比代码层面的“先查再插”更可靠。CREATE TABLE wx_transfer_order ( id BIGINT PRIMARY KEY AUTO_INCREMENT, partner_trade_no VARCHAR(32) NOT NULL COMMENT 商户转账单号, payment_no VARCHAR(32) COMMENT 微信付款单号, openid VARCHAR(64) NOT NULL, amount INT NOT NULL COMMENT 金额单位分, status VARCHAR(20) NOT NULL DEFAULT PENDING, create_time DATETIME DEFAULT CURRENT_TIMESTAMP, update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, UNIQUE KEY uk_partner_trade_no (partner_trade_no) ) COMMENT微信转账订单表;partner_trade_no上的唯一索引是最后防线插入前先检查订单状态插入后执行付款。如果再次收到同一单号的请求直接查库返回已有状态不再调微信。状态机建议简化为PENDING待处理→SENDING调接口成功→SUCCESS到账/FAILED明确失败。这里有个细节如果第一次调用微信时网络超时代码抛异常但微信侧可能已经受理。这时不能直接把订单标记为失败而应该进入“查单补偿流程”用同一partner_trade_no去查单。微信查单接口天然支持幂等重复查询不会产生副作用。5.3 对账与异常补偿下载对账单、定时补单定时任务只能解决“我方认为未发微信认为已发”的补偿但还有“我方认为已到账实际未到账”的极端情况。终极手段是对账。微信提供下载对账单接口/pay/downloadbill按天拉取交易流水然后和本地订单表逐笔比对。public async Taskstring DownloadBillAsync(string billDate) { var dict new SortedDictionarystring, string { { appid, _config.AppId }, { mch_id, _config.MchId }, { bill_date, billDate }, // 格式yyyyMMdd { bill_type, ALL }, { nonce_str, Guid.NewGuid().ToString(N).Substring(0, 16) } }; string sign WxSign.BuildSign(dict, _config.ApiKey); dict.Add(sign, sign); string xml XmlHelper.MapToXml(dict); // 注意对账单接口返回的不是XML而是纯文本流水 return await PostXmlAsync( https://api.mch.weixin.qq.com/pay/downloadbill, xml); }对账单返回的是文本表格每行用逗号分隔交易时间、公众账号ID、商户号、特约商户号、设备号、微信订单号、商户订单号、用户标识、交易类型、交易状态、付款银行、货币种类、应结金额、代金券金额、微信退款单号、商户退款单号、退款金额、充值券退款金额、退款类型、退款状态等。解析时跳过前两行表头和最后一行统计汇总。对账发现问题后补偿逻辑按优先级处理先查单确认实际状态状态不一致以微信对账单为准并修正本地单发现微信有记录而本地没有的订单立即进入人工审核多半是回调丢失或程序中途崩溃。对账建议每天凌晨跑一次拉前一天的账单避免账单还没生成时去拉导致空文件。6. 二次开发改造从企业付款到新版商家转账与银行卡扩展6.1 升级到V3商家转账接口地址与签名方式的变化老版企业付款到零钱接口应该还能用但微信已经在力推新版“商家转账”接口。升级的核心变化有三个接口变成POST /v3/transfer/batches签名从MD5换成微信支付V3签名基于商户API私钥的SHA256-RSA2048不再需要客户端证书而是靠Authorization头带签名串。如果你拿到的DEMO还是老版改造时不要试图原地硬改建议把老版Service里的“参数组装”和“HTTP传输”彻底解耦。新增一个WxV3TransferService复用WxTransferService里的订单状态管理和对账逻辑只替换协议交互层。V3接口请求体长这样{ appid: wx1234567890, out_batch_no: 20240115001, batch_name: 用户提现, batch_remark: 1月提现批次, total_amount: 1000, total_num: 1, transfer_detail_list: [ { out_detail_no: 20240115001001, transfer_amount: 1000, transfer_remark: 提现, openid: o1234567890, user_name: 张三 } ] }V3接口支持异步回调微信会在转账成功后往你配置的回调URL推POST通知。这比老版的主动查单舒服很多但仍建议保留定时查单兜底因为回调也可能丢。改造时多花一小时把回调验签做对值得。6.2 扩展从付款到零钱改造为转账到银行卡如果你的业务不只是微信零钱提现还要支持“企业付款到银行卡”核心改动很小。老版有专门的/mmpaymkttransfers/promotion/transfers接口变种参数从openid换成enc_bank_no收款方银行卡号和enc_true_name收款方姓名这两个字段需要用商户公钥加密。签名方式、证书加载、回调处理与零钱版完全一致。我建议在WxTransferService里抽象一个TransferMethod枚举让上层根据提现渠道走不同分支public enum TransferMethod { WxWallet, // 微信零钱 BankCard // 银行卡 }每种业务的参数校验逻辑不同但签名工具和HTTP客户端完全复用。这样下次微信出新渠道你只需要加一个枚举值和一个参数组装方法不用动核心框架。6.3 验证方法小额实测与日志链路改完代码怎么验证我的习惯是先在测试商户号上跑“最低金额测试”给自己的微信openid转0.30元验证签名、证书、余额扣款、到账通知全链路。然后跑异常场景故意传错签名、传不存在的openid、传低于30分的金额确认每个错误分支都返回友好提示而不是堆栈。日志是最后一道防线。支付模块建议用结构化日志把partner_trade_no、openid、amount、err_code、err_code_des全部打进去每笔调用串成一个traceId。线上排查问题时拿着用户提供的商户单号一搜日志从收到请求到微信返回再到查单确认链路清清楚楚。从那以后我每次改支付代码都会强制走一遍“签名日志打印 最低金额实测 错误分支回归”三步缺一步都不放心上线。希望这篇拆解能帮你少踩几个坑把DEMO稳稳跑起来。本文还有配套的精品资源点击获取