简介面向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, IDictionarystring, string headers, out PayNotifyData notifyData); }CreateOrder管下单QueryOrder兜底查单Refund处理退款VerifyNotify只做一件事把微信/支付宝/银联各不相同的回调报文和验签逻辑收口到一个入口。这样业务层无论接哪个渠道都只需要调用这五个接口。三家渠道的核心差异我用一张表固定下来后续所有适配器都围绕这张表设计和做单元测试维度微信支付支付宝银联在线金额单位分整数元两位小数元两位小数回调格式V3 JSON / V2 XML表单参数KeyValue 键值对签名算法V3 RSA-SHA256 / V2 MD5RSA2SHA256RSAWithSHA256证书体系商户证书平台证书应用私钥支付宝公钥签名证书验签证书签名原串请求体原样参与剔除 sign/sign_type 后按字典序拼接按文档指定字段拼接退款通知有独立回调与支付通知同接口有独立交易码2.2 SignContext 签名分发器把“黑匣子”变成可替换策略签名是支付对接里最玄学的部分。同一个字符串官方文档工具能验证通过代码里就是失败。我一般不会在适配器里直接写三个 if/else 分支去调不同签名方法而是把签名器注册成一个策略集合渠道参数一进来自动路由到对应实现public class SignContext { private readonly Dictionarystring, ISigner _signers; public SignContext(IEnumerableISigner 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:ss08: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_amountvar formParams new Dictionarystring, 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 文件加载的商户证书验签证书是另外一份公钥证书两套证书还分测试环境和生产环境文件名长得几乎一样非常容易搞混。银联网关支付下单核心参数如下参数名取值示例说明txnType0101 表示消费31 表示退费txnSubType00默认消费子类channelType0707 互联网08 移动端merId商户号测试环境和生产环境不同orderId业务侧流水号同一商户号下唯一txnTimeyyyyMMddHHmmss交易时间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 段拦了。另外回调地址如果带了?fromxxx这种 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(Dictionarystring, 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 和并发优化。支付这条路先把“收到通知不慌、验签不糊弄、重放不重复”三件事做扎实比什么花哨设计都管用。希望帮到你。本文还有配套的精品资源点击获取
简介面向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, IDictionarystring, string headers, out PayNotifyData notifyData); }CreateOrder管下单QueryOrder兜底查单Refund处理退款VerifyNotify只做一件事把微信/支付宝/银联各不相同的回调报文和验签逻辑收口到一个入口。这样业务层无论接哪个渠道都只需要调用这五个接口。三家渠道的核心差异我用一张表固定下来后续所有适配器都围绕这张表设计和做单元测试维度微信支付支付宝银联在线金额单位分整数元两位小数元两位小数回调格式V3 JSON / V2 XML表单参数KeyValue 键值对签名算法V3 RSA-SHA256 / V2 MD5RSA2SHA256RSAWithSHA256证书体系商户证书平台证书应用私钥支付宝公钥签名证书验签证书签名原串请求体原样参与剔除 sign/sign_type 后按字典序拼接按文档指定字段拼接退款通知有独立回调与支付通知同接口有独立交易码2.2 SignContext 签名分发器把“黑匣子”变成可替换策略签名是支付对接里最玄学的部分。同一个字符串官方文档工具能验证通过代码里就是失败。我一般不会在适配器里直接写三个 if/else 分支去调不同签名方法而是把签名器注册成一个策略集合渠道参数一进来自动路由到对应实现public class SignContext { private readonly Dictionarystring, ISigner _signers; public SignContext(IEnumerableISigner 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:ss08: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_amountvar formParams new Dictionarystring, 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 文件加载的商户证书验签证书是另外一份公钥证书两套证书还分测试环境和生产环境文件名长得几乎一样非常容易搞混。银联网关支付下单核心参数如下参数名取值示例说明txnType0101 表示消费31 表示退费txnSubType00默认消费子类channelType0707 互联网08 移动端merId商户号测试环境和生产环境不同orderId业务侧流水号同一商户号下唯一txnTimeyyyyMMddHHmmss交易时间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 段拦了。另外回调地址如果带了?fromxxx这种 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(Dictionarystring, 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 和并发优化。支付这条路先把“收到通知不慌、验签不糊弄、重放不重复”三件事做扎实比什么花哨设计都管用。希望帮到你。本文还有配套的精品资源点击获取
