简介：面向C# .NET开发人员的多支付渠道整合方案，聚焦微信、支付宝与银联支付在统一业务后台中的接入与协同。内容覆盖微信JSAPI、Native、H5、APP，支付宝网页支付、APP支付、扫码支付，以及银联网上支付、快捷支付等典型场景，从SDK引入、参数配置到预支付订单生成、支付结果异步回调与订单状态同步，再到退款、撤销等逆向操作均有说明。压缩包约52.91MB，文件总数与类型清单暂未提供。目前已有1493人学习下载。对实际开发而言，资料重点强调了商户密钥加密、回调验签、异常处理机制及沙箱环境测试等关键事项，并给出一个名为Payment.Api的支付服务接口层设计思路，可将不同支付方式的交互逻辑封装为统一API，降低业务代码耦合度。适合正在搭建支付模块的中高级.NET工程师参考。
1. C#.NET整合微信、支付宝、银联支付：先把回调扛住，再谈下单
做 C#.NET 支付整合，很多开发者的第一反应是先把三家的下单接口调通。实际翻车点几乎都集中在下单之后的异步通知环节：微信、支付宝、银联各自的回调协议、签名算法、通知重试策略完全不一样，白天订单显示“支付成功”，晚上对账发现库里几十笔单子还是“待支付”，问题全出在回调丢失或验签失败上。这套 C#.NET 全渠道支付整合资源，做的不是给你各贴一个 SDK 示例，而是把微信、支付宝、银联揉进同一个网关层，统一处理参数、验签、追溯、退款。适合刚接手支付模块、想在最短时间内跑通三条渠道并避开回调坑的 .NET 从业者。
2. 统一支付网关抽象：把三种渠道的请求、签名、回调揉进同一套接口
2.1 统一支付模型：金额单位和订单号规则先定死
三家渠道放在一起，最容易出问题的不是接口能不能调通，而是数据模型不统一。微信支付金额单位是分，支付宝和银联是元（支付宝最多两位小数），回调报文里微信 V3 返回 JSON、V2 返回 XML，支付宝返回表单参数，银联返回定长报文。如果每个渠道在自己的 Service 里各写一套参数封装，后面每升级一个 SDK，业务代码就要跟着改一遍。
我先定义一个公共支付请求模型，业务层只认这一个对象：
public class PayRequest { public string Channel { get; set; } // wxpay / alipay / unionpay public string OutTradeNo { get; set; } // 商户订单号，全局唯一 public decimal Amount { get; set; } // 统一用元，适配器内部处理单位 public string Subject { get; set; } // 订单标题 public string NotifyUrl { get; set; } // 异步通知地址 public string Scene { get; set; } // 微信:JsAPI/Native/H5 支付宝:page/app/wap public string OpenId { get; set; } // 微信 JsAPI 必填 public string ClientIp { get; set; } // 下单终端 IP public int ExpireMinutes { get; set; } = 15; // 交易有效期，默认 15 分钟 }这里我推荐业务层统一用decimal存金额，进适配器再转各渠道单位。原因很简单：你很难保证所有开发者在业务层都记得“微信要乘 100”，但你可以保证所有渠道适配器都遵循相同的内部转换规则。OutTradeNo必须做到整表唯一，不能微信渠道用一套流水号、支付宝又用另一套，否则后面按订单号查单和退款会非常难受。
接口层定义五个核心能力，所有渠道适配器实现同一套契约：
public interface IPayService { PayResponse CreateOrder(PayRequest request); PayResponse QueryOrder(string outTradeNo); PayResponse Refund(RefundRequest request); bool VerifyNotify(string channel, string rawBody, IDictionary<string, string> headers, out PayNotifyData notifyData); }CreateOrder管下单，QueryOrder兜底查单，Refund处理退款，VerifyNotify只做一件事：把微信/支付宝/银联各不相同的回调报文和验签逻辑收口到一个入口。这样业务层无论接哪个渠道，都只需要调用这五个接口。
三家渠道的核心差异我用一张表固定下来，后续所有适配器都围绕这张表设计和做单元测试：
| 维度 | 微信支付 | 支付宝 | 银联在线 |
|---|---|---|---|
| 金额单位 | 分（整数） | 元（两位小数） | 元（两位小数） |
| 回调格式 | V3 JSON / V2 XML | 表单参数 | KeyValue 键值对 |
| 签名算法 | V3 RSA-SHA256 / V2 MD5 | RSA2（SHA256） | RSAWithSHA256 |
| 证书体系 | 商户证书+平台证书 | 应用私钥+支付宝公钥 | 签名证书+验签证书 |
| 签名原串 | 请求体原样参与 | 剔除 sign/sign_type 后按字典序拼接 | 按文档指定字段拼接 |
| 退款通知 | 有独立回调 | 与支付通知同接口 | 有独立交易码 |
2.2 SignContext 签名分发器：把“黑匣子”变成可替换策略
签名是支付对接里最玄学的部分。同一个字符串，官方文档工具能验证通过，代码里就是失败。我一般不会在适配器里直接写三个 if/else 分支去调不同签名方法，而是把签名器注册成一个策略集合，渠道参数一进来，自动路由到对应实现：
public class SignContext { private readonly Dictionary<string, ISigner> _signers; public SignContext(IEnumerable<ISigner> signers) { _signers = signers.ToDictionary(s => s.Channel); } public string Sign(string channel, string content) { if (_signers.TryGetValue(channel, out var signer)) { return signer.Sign(content); } throw new NotSupportedException($"未注册的支付渠道: {channel}"); } }这里的设计要点是把“算法选型”放到程序启动时注册，而不是散落在各处。以后新接一个渠道，只需新增一个实现ISigner的类，无需改动现有业务代码。签名上下文只负责“签名原串进来，签名值出去”，至于原串怎么拼，那是每个适配器的职责。调试的时候也方便——打印签名原串，所有渠道统一用同一套日志格式，一眼看出拼串错在哪。
提示：签名原串的构造是整个支付对接最容易翻车的地方，也是这份资源里适配器层最值得看的部分。后面章节会逐个渠道拆开讲。
3. 微信支付适配器：JsAPI、Native、H5 三种场景的调用链差异
3.1 三种支付模式怎么选：先看用户在哪里付款
微信支付的模式选择直接决定下单参数，很多新人在这上面反复横跳。用一张判断链就能定下来：
- 用户是在微信内打开的页面，比如公众号菜单、小程序内嵌 WebView，用 JsAPI 支付，需要传
openid，请求头带用户授权信息。 - 用户是在电脑浏览器访问商城 PC 端，用 Native 支付，下单后返回
code_url，前端拿这个 URL 生成二维码让用户扫码。 - 用户是在手机浏览器（非微信环境）看到商品页，用 H5 支付，下单后返回
h5_url，前端直接跳转拉起微信付款。
三种模式最大的差异在于支付方式标识和前端交互，后端统一下单的核心字段不变。以 Native 为例，微信 V3 下单的核心代码：
// 微信 V3 Native 下单 var body = JsonSerializer.Serialize(new { appid = _wxOptions.AppId, mchid = _wxOptions.MchId, description = request.Subject, out_trade_no = request.OutTradeNo, notify_url = request.NotifyUrl, time_expire = DateTime.Now.AddMinutes(request.ExpireMinutes) .ToString("yyyy-MM-ddTHH:mm:ss+08:00"), amount = new { total = (int)(request.Amount * 100), // 微信以分为单位 currency = "CNY" } });这段代码里有几个参数值得反复确认。time_expire是绝对时间，超过后微信会拒绝该订单，我生产环境通常设置 15~30 分钟，避免用户创建订单后迟迟不付款占住库存。amount.total是整数分，很多人在这里直接取request.Amount导致多付一百倍，这是支付对账最常见的低级事故。notify_url必须是外网可访问的 HTTPS 地址，而且不能带 query string，带上了微信会直接报参数错误。
微信 V3 的接口要求所有请求都带Authorization头和商户证书序列号，使用 HTTP 客户端时还需要加载商户私钥做客户端证书签名。常见做法是封装一个WechatPayHttpClient，专门处理头信息和证书，业务代码不直接碰HttpClient。
3.2 统一下单与回调验签的调用链：V3 和 V2 是两个物种
微信支付的版本差异是绕不开的坑。V2 回调报文是 XML，验签规则是 MD5 或 HMAC-SHA256 加密钥；V3 回调报文是 JSON，验签是对请求头的Wechatpay-Timestamp、Wechatpay-Nonce、Wechatpay-Signature三个字段做验签。如果资源里的代码基于 V3，那你在回调入口看到的是：
// 微信 V3 回调验签 string message = timestamp + "\n" + nonce + "\n" + rawBody + "\n"; var cert = _platformCertificateProvider.GetCertificate(serialNo); using var rsa = cert.GetRSAPublicKey(); bool valid = rsa.VerifyData( Encoding.UTF8.GetBytes(message), Convert.FromBase64String(signature), HashAlgorithmName.SHA256, RSASignaturePadding.Pkcs1);这里的message拼接顺序是固定的，换一个顺序验签必失败。rawBody必须是请求体的原始字符串，不能用JsonConvert.DeserializeObject之后再重新序列化的内容，因为字段顺序和转义方式可能已经变了。很多情况下验签失败，问题不是证书问题，而是开发者在中间把 body 重新反序列化了一次。
V2 和 V3 的验签入口虽然不同，但VerifyNotify接口在适配器层已经屏蔽了差异。业务层拿到PayNotifyData对象后，只关心订单号、支付金额、支付状态和时间，不关心底层报文格式。
微信的回调还会因为网络抖动重复发送，所以处理完验签之后的第一件事不是改订单状态，而是查一下本地幂等表，确认这是一笔新通知还是重发通知。这个细节放到第 5 章展开。
4. 支付宝与银联适配器：签名规则反着来，参数最容易串位
4.1 支付宝：页面跳转支付与异步通知验签的参数差异
支付宝在 .NET 环境最常见的是电脑网站支付（alipay.trade.page.pay）和手机网站支付（alipay.trade.wap.pay）。下单接口返回的是表单或跳转字符串，业务层一般直接渲染到页面上让用户提交。
支付宝的参数设计和微信是反着来的。微信强调“金额用分、签名字符串是原始 body”，支付宝强调“金额用元、签名需要按字典序拼接所有非空参数”。同样一笔订单，微信的amount是个嵌套对象，支付宝则是平铺的total_amount：
var formParams = new Dictionary<string, string> { ["app_id"] = _aliOptions.AppId, ["method"] = "alipay.trade.page.pay", ["charset"] = "utf-8", ["sign_type"] = "RSA2", ["timestamp"] = DateTime.Now.ToString("yyyy-MM-dd HH:mm:ss"), ["version"] = "1.0", ["notify_url"] = request.NotifyUrl, ["biz_content"] = JsonSerializer.Serialize(new { out_trade_no = request.OutTradeNo, total_amount = request.Amount.ToString("0.00"), subject = request.Subject, product_code = "FAST_INSTANT_TRADE_PAY" }) };支付宝官方文档里的公共参数只列了字典，没有强调“参与签名的参数必须排除sign和sign_type”。这两个字段一旦混进签名原串，验签百分之百失败。而且支付宝的total_amount是字符串类型，不能用decimal直接序列化，否则可能输出9.9而不是9.90，支付宝会提示金额格式错误。
支付宝异步通知验签，签名原串是“剔除sign、sign_type后，其余参数按字典序拼接”：
// 支付宝异步通知验签 var sortedParams = formParams .Where(x => x.Key != "sign" && x.Key != "sign_type") .Where(x => !string.IsNullOrEmpty(x.Value)) // 空值不参与签名 .OrderBy(x => x.Key, StringComparer.Ordinal) .Select(x => $"{x.Key}={x.Value}"); string signContent = string.Join("&", sortedParams); bool valid = _aliSigner.Verify(signContent, sign, "RSA2");排序用的StringComparer.Ordinal是按字节排序，不是按本地化语言的字符排序。如果用了默认的StringComparer.CurrentCulture，某些边界场景（比如大小写混合参数）会拼出不同顺序。支付宝验签失败的第一排查动作，就是把这个signContent和支付宝开放平台调试工具生成的签名原串逐字对比，差一个空格都能导致失败。
4.2 银联：证书体系、交易类型码和退款查单
银联是支付对接里最需要耐心的渠道。它不是协议复杂，而是证书体系跟微信支付宝完全不同。微信支付宝用公私钥对加签，银联的签名证书是用 PFX 文件加载的商户证书，验签证书是另外一份公钥证书，两套证书还分测试环境和生产环境，文件名长得几乎一样，非常容易搞混。
银联网关支付下单，核心参数如下：
| 参数名 | 取值示例 | 说明 |
|---|---|---|
| txnType | 01 | 01 表示消费，31 表示退费 |
| txnSubType | 00 | 默认消费子类 |
| channelType | 07 | 07 互联网，08 移动端 |
| merId | 商户号 | 测试环境和生产环境不同 |
| orderId | 业务侧流水号 | 同一商户号下唯一 |
| txnTime | yyyyMMddHHmmss | 交易时间，14 位 |
| certId | 证书序列号 | 从 PFX 证书里读取 |
| signature | 签名值 | 加签后放入报文 |
银联下单和退款的报文结构相同，区别只在txnType。很多人退费用了01，银联直接返回交易类型不支持，看到这个报错第一反应不是改参数，而是去查接口文档。另一个高频坑是银联的certId，它不是商户号也不是证书文件名，必须通过 PFX 文件加载后用X509Certificate2实例读取。如果把证书文件路径或者文件名当certId传进去，签名验证阶段就会报错。
银联退款状态查询跟交易查询是两套接口，查询响应里有queryId、traceNo、respCode等多个状态字段，判断成功不能只看respCode == "00"，还要确认transactionType和origRespCode。这里最容易犯的错误是把“请求受理成功”当成“退款成功”，银联的respCode == 00只代表报文受理成功，真实资金处理结果要看异步通知。
每接一个渠道，我都会在适配器里放一个BuildDebugLog方法，把发送报文、签名字符串、响应报文完整记录到单独日志文件里。尤其是银联，上线初期没有这个日志，出了问题连排查入口都找不到。
5. 支付接入避坑：异步通知、金额单位、证书过期的四个翻车案例
5.1 回调丢失导致订单悬挂
现象：用户支付成功，业务系统订单状态一直停在“待支付”，用户反复找客服，技术人员查不到任何回调请求日志。
原因：最常见的不是微信或者支付宝没发回调，而是回调地址本身不可达。有人测试环境用了localhost:8080/notify，内网没问题，一上公网就完蛋；还有人的服务器防火墙只放行了 80/443 访问入口，却把支付平台回调的 IP 段拦了。另外，回调地址如果带了?from=xxx这种 query string，部分渠道平台会直接忽略通知。
解决：回调地址固定为独立 HTTPS 域名，不跟 H5 商城页面共用路径，避免网关层把支付平台的请求当普通流量拦截。上线前先到渠道商户平台手动发一笔测试通知，确认入口日志有请求进来。我一般会在回调入口的第一行日志打印request.Path和原始 body 长度，不打印完整 body，防止敏感信息泄进日志。
5.2 金额单位不一致导致对账失败
现象：数据库订单金额 9.90 元，支付成功回调里金额字段也是 9.90，但业务层判定金额不一致，拒绝更新订单状态。
原因：数据库存的是decimal，微信回调返回的是分（990），支付宝回调返回的是元字符串（9.90）。业务层直接拿decimal跟字符串比较，等于用一袋苹果跟一筐梨对数量。
解决：我在数据库里加两个字段：pay_amount_fen（整数分）和pay_amount_yuan（字符串原值），对账永远以“分”为准。各渠道适配器在回调解析阶段就把金额转成统一单位，业务层不做任何换算。数据表里同时保留原值字段，出了问题可以直接跟支付平台账单逐笔核对。
5.3 验签“永远失败”的三种内部原因
现象：同一个参数串，在微信支付调试工具里验签通过，代码里就是false；支付宝异步通知验签，本地一模一样的参数也失败。
原因：三个内部细节，按概率排序。一是签名原串构造时没有排除空值参数，支付宝签名原串的空值要过滤，微信 V3 的空值在 JSON 序列化后可能导致字段顺序不同；二是参与验签的内容用了反序列化后的对象，而不是原始请求体字符串；三是 RSA2 签名用了 SHA1 去验签，支付宝sign_type写的是 RSA2，代码里却用HashAlgorithmName.SHA1。
解决：验签入口强制统一走VerifyNotify，代码中签名原串生成后立即输出到日志，并与各渠道的调试工具逐字对比。我在适配器里放了一个SignDebugDump()方法，启动配置里打开即可。
5.4 证书过期全渠道突然同时翻车
现象：某一天开始，微信支付、银联支付的请求全部返回签名相关错误，支付宝没有受影响，业务侧没有任何改动。
原因：微信平台证书和银联商户证书都有有效期，证书到期后签名验证直接失效。微信严格来说是平台证书，银联是商户上传的签名证书，两套证书到期时间不一样，但任何一个失效都会表现为支付链路全挂。
解决：把证书文件统一放到密钥管理服务，别放项目目录里。我前几年踩过这个坑，证书埋在代码目录里，到期前没人记得换，那天下班前线上全线报签名错，第二天卡着商户平台补了证书才恢复。从那以后，我写了证书到期巡检脚本，提前 30 天和提前 7 天各告警一次，并把证书到期时间同步到对账单里。还有一点，换证书之后，旧的证书私钥文件不要直接删，留一个版本备份，方便排查历史支付单的验签问题。
6. 上线前先跑回调模拟器：用预签名报文把验签和幂等链路打通
6.1 用预签名报文本地跑通回调链路
支付联调最痛苦的是依赖真实支付。为了验签逻辑跑通，你等用户真的扫一笔码，等异步通知进来，整个联调周期拖得非常长。我习惯在资源里保留一个回调模拟组件，它在本地生成一笔“已支付”的假回调报文，并且用真实的商户私钥做签名，直接把请求打到本地回调地址：
public static string BuildSignedCallback(Dictionary<string, string> data, string channel) { var signContent = string.Join("&", data .Where(x => x.Key != "sign" && x.Key != "sign_type") .Where(x => !string.IsNullOrEmpty(x.Value)) .OrderBy(x => x.Key, StringComparer.Ordinal) .Select(x => $"{x.Key}={x.Value}")); var sign = SignContext.Sign(channel, signContent); data.Add("sign", sign); return JsonSerializer.Serialize(data); }这段代码的原理是：先按各渠道的签名规则构造原串，再用真实私钥生成签名，然后模拟渠道平台把回调打到你本地服务。本地开发环境用这个组件，可以在不扫码、不真实付款的情况下，把VerifyNotify逻辑完整跑一遍，包括验签、金额核对、订单状态流转。
实际执行时，我会分三步验证：第一步用伪造的坏签名发一笔，确认VerifyNotify返回 false；第二步用预签名组件发一笔，确认返回 true 且订单状态变成已支付；第三步把同一笔报文连续发送两次，验证幂等表能不能挡住重复通知。这三步在测试环境全绿，我才会进入真实支付联调。
6.2 幂等流水表：把重复通知变成可控状态
回调模拟器能跑出重复报文，真实环境里微信和银联也会因为网络原因重发通知。保持幂等不能只依赖在代码里判断“订单已经是已支付就不更新”，那个入口在并发下会被穿透。真正能扛住的是流水表唯一索引：
CREATE TABLE pay_callback_log ( id BIGINT PRIMARY KEY AUTO_INCREMENT, channel VARCHAR(16) NOT NULL, out_trade_no VARCHAR(64) NOT NULL, transaction_id VARCHAR(64), raw_body TEXT, status TINYINT NOT NULL DEFAULT 0, create_time DATETIME NOT NULL, UNIQUE KEY uk_channel_trade (channel, out_trade_no) );这个表的唯一索引建在(channel, out_trade_no)上，微信、支付宝、银联三个渠道各自的同一笔订单，只允许插一条流水。第二次回调到达时，唯一索引直接拦住插入，代码捕获到重复键异常后进入更新分支，把raw_body覆盖写入，status保持不变。订单状态的更新走状态机：待支付→支付成功→退款中→已退款，任何一步出现逆向状态跳转，代码直接报错并告警。
从那以后，我每次上线新渠道，都强制自己先跑一遍回调模拟器和幂等重放测试，再谈 TPS 和并发优化。支付这条路，先把“收到通知不慌、验签不糊弄、重放不重复”三件事做扎实，比什么花哨设计都管用。希望帮到你。
本文还有配套的精品资源，点击获取
