后端即时通讯金融科技【免费下载链接】WeiXinMPSDK微信全平台 .NET SDK Senparc.Weixin for C#支持 .NET Framework 及 .NET Core、.NET 10.0。已支持微信公众号、小程序、小游戏、微信支付、企业微信/企业号、开放平台、JSSDK、微信周边等全平台。 WeChat SDK for C#.项目地址https://gitcode.com/gh_mirrors/we/WeiXinMPSDK点击查看免费下载本文基于 WeiXinMPSDK 官方文档 Native Payments 指南 展开完整讲解微信支付 V3 的 Native 支付扫码支付全流程如何在 Controller 中调用BasePayApis.NativeAsync下单获取code_url、如何用 ZXing.Net 生成支付二维码、前端如何嵌入二维码以及支付完成后的异步回调验签与订单处理。读完后你可以直接在 ASP.NET Core 项目中落地一套可运行的 Native 支付方案。一、什么是 Native 支付Native 支付用于线下或微信环境以外的支付场景商户在服务端生成一个支付二维码用户使用微信“扫一扫”扫描后唤起个人微信支付完成付款。其典型交互链路为商户服务端调用微信“Native 支付下单接口”提交订单信息商品描述、商户订单号、金额、回调地址等微信返回code_url用于生成二维码的支付链接商户将code_url编码为二维码图片展示给用户PC 网页、收银台屏幕等用户微信扫码完成支付微信服务器异步请求商户在下单时设置的notify_url回调地址推送支付结果商户验签并确认trade_state SUCCESS后更新订单状态、发货或发放权益并返回规定格式的应答。由于 Native 支付不依赖用户身处微信客户端内用户只需用手机微信扫一下它是 PC 网站、H5 外部页面、线下收银台最常用的支付方式与需要在微信浏览器内调起 JSAPI 支付的场景形成互补。二、创建 Native 支付端点完整示例代码WeiXinMPSDK 的示例项目Samples/TenPayV3/Senparc.Weixin.Sample.TenPayV3中Native 支付的完整实现在 TenPayApiV3Controller.cs 的NativePayCode方法中。该端点接收商品参数调用微信下单接口后直接返回一张 PNG 二维码图片/// summary /// 使用 Native 支付 /// /summary /// param nameproductId/param /// param namehc/param /// returns/returns public async TaskIActionResult NativePayCode(int productId, int hc) { var products ProductModel.GetFakeProductList(); var product products.FirstOrDefault(z z.Id productId); if (product null || product.GetHashCode() ! hc) { return Content(商品信息不存在或非法进入2004); } //使用 Native 支付输出二维码并展示 MemoryStream fileStream null;//输出图片的URL var price (int)(product.Price * 100); var name product.Name - 微信支付 V3 - Native 支付; var sp_billno string.Format({0}{1}{2}, TenPayV3Info.MchId/*10位*/, SystemTime.Now.ToString(yyyyMMddHHmmss), TenPayV3Util.BuildRandomStr(6)); var notifyUrl TenPayV3Info.TenPayV3Notify.Replace(/TenpayApiV3/, /TenpayApiV3/); TransactionsRequestData requestData new(TenPayV3Info.AppId, TenPayV3Info.MchId, name, sp_billno, new TenpayDateTime(DateTime.Now.AddHours(1)), null, notifyUrl, null, new() { currency CNY, total price }, null, null, null, null); BasePayApis basePayApis new BasePayApis(); var result await basePayApis.NativeAsync(requestData); //进行安全签名验证 if (result.VerifySignSuccess true) { fileStream QrCodeHelper.GerQrCodeStream(result.code_url); } else { fileStream QrCodeHelper.GetTextImageStream(Native Pay 未能通过签名验证无法显示二维码); } return File(fileStream, image/png); }关键点逐项解析要素说明productIdhchc是商品对象的 HashCode作为简单的“商品合法性”校验参数防止非法构造商品 ID 直接下单price(int)(product.Price * 100)微信支付 V3 的金额单位为分示例中把元转换为分sp_billno即out_trade_no由“10 位商户号 时间戳 6 位随机串”拼接需保证同一商户下唯一。示例注释中提醒访问量较大时建议增加订单流水号的去重检查time_expirenew TenpayDateTime(DateTime.Now.AddHours(1))订单有效时间此处为下单后 1 小时过期微信要求 RFC 3339 时间格式notifyUrl支付结果异步通知地址取自商户配置TenPayV3Info.TenPayV3Notifyamountnew() { currency CNY, total price }货币类型 总金额分TenPayV3Info包含AppId、MchId、TenPayV3Notify等来自 TenPayV3InfoCollection 的注册配置示例中通过TenPayHelper.GetRegisterKey(Config.SenparcWeixinSetting)取得注册键后取出对应配置见 TenPayApiV3Controller.cs。三、SDK 源码层面NativeAsync 如何调用微信接口示例中basePayApis.NativeAsync(requestData)一行背后的实现在 BasePayApis.cspublic async TaskNativeReturnJson NativeAsync(TransactionsRequestData data, int timeOut Config.TIME_OUT) { try { var url BasePayApis.GetPayApiUrl(Senparc.Weixin.Config.TenPayV3Host /{0}v3/pay/{1}transactions/native, data?.sp_mchid); TenPayApiRequest tenPayApiRequest new(_tenpayV3Setting); return await tenPayApiRequest.RequestAsyncNativeReturnJson(url, data, timeOut); } catch (Exception ex) { SenparcTrace.BaseExceptionLog(ex); return new NativeReturnJson() { ResultCode new TenPayApiResultCode() { ErrorMessage ex.Message } }; } }从源码结构看SDK 为 Native 支付封装了几个值得注意的细节请求地址https://api.mch.weixin.qq.com/v3/pay/transactions/native直连商户GetPayApiUrl会根据配置自动拼接沙箱前缀与服务商partner/路径BasePayApis.cs请求签名TenPayApiRequest会基于ISenparcWeixinSettingForTenpayV3中配置的 APIv3 密钥、商户证书自动构造 WECHATPAY2-SHA256-RSA2048 请求签名头并对响应进行验签结果体现在返回对象的VerifySignSuccess属性上服务商模式若TransactionsRequestData.sp_mchid非空URL 中会自动插入partner/用于服务商代子商户下单构造函数约束BasePayApis在初始化时会校验EncryptionType证书加密类型未设置直接抛WeixinExceptionBasePayApis.cs。不传参数时回退到全局Senparc.Weixin.Config.SenparcWeixinSetting.TenpayV3Setting这也是示例中可以直接new BasePayApis()的原因。调用成功后NativeReturnJson中的code_url即为支付二维码内容格式形如weixin://wxpay/bizpayurl?...。示例代码在验签失败时会渲染一张提示文字图片而非抛出异常避免收银页面出现 500 错误。四、二维码生成基于 ZXing.Net 的 QrCodeHelper文档指出生成二维码的控件很多示例采用 ZXing.Netpublic static MemoryStream GerQrCodeStream(string url) { BitMatrix bitMatrix new MultiFormatWriter().encode(url, BarcodeFormat.QR_CODE, 300, 300); var bw new ZXing.BarcodeWriterPixelData(); // ...将 BitMatrix 转为 32bpp Bitmap 并写入 PNG 内存流... bitmap.Save(fileStream, System.Drawing.Imaging.ImageFormat.Png); fileStream.Seek(0, SeekOrigin.Begin); return fileStream; }GerQrCodeStream(code_url)将微信返回的支付链接编码为 300×300 的 QR 码 PNG 内存流GetTextImageStream(text)验签失败等异常分支下渲染一张带提示文字的 PNG让用户直观看到“无法显示二维码”的原因。注意源码中对MemoryStream先Flush()、再Position 0的处理这是 .NET Core 下向响应写出图片流的必要步骤。前端嵌入方式端点直接输出image/png因此前端只需要一个img标签即可展示支付二维码img src/TenpayApiV3/NativePayCode alt扫码付款 /实际示例页面 ProductItem.cshtml 中携带了商品参数img srcUrl.Action(NativePayCode, new { productId Model.Id, hc Model.GetHashCode() }) altNative支付二维码 /也就是说用户访问商品详情页 → 页面内嵌二维码图片 → 浏览器请求NativePayCode端点 → SDK 实时下单并返回全新二维码。该模式下每张二维码对应一笔实时生成的新订单新的out_trade_no扫码即完成这笔订单的支付。五、支付异步回调解密、验签与订单确认用户扫码完成支付后微信服务器会自动请求下单时设置的回调地址notify_url。官方文档中该部分代码标注为“待补充”仓库中对应的完整实现正是 TenPayApiV3Controller.cs 的PayNotifyUrl方法示例中TenPayV3Info.TenPayV3Notify指向该端点端点名称可按项目自行命名如/TenpayApiV3/NativeNotifyUrl/// summary /// JSAPI支付回调地址在下单接口中设置的 notify_url /// /summary public async TaskIActionResult PayNotifyUrl() { //获取微信服务器异步发送的支付通知信息 var resHandler new TenPayNotifyHandler(HttpContext); var orderReturnJson await resHandler.DecryptGetObjectAsyncOrderReturnJson(_isPublicKey); //记录日志 Senparc.Weixin.WeixinTrace.SendCustomLog(PayNotifyUrl 接收到消息, orderReturnJson.ToJson(true)); //演示记录 transaction_id实际开发中需要记录到数据库以便退款和后续跟踪 TradeNumberToTransactionId[orderReturnJson.out_trade_no] orderReturnJson.transaction_id; //获取支付状态 string trade_state orderReturnJson.trade_state; //验证请求是否从微信发过来安全 NotifyReturnData returnData new(); //验证可靠的支付状态 if (orderReturnJson.VerifySignSuccess true trade_state SUCCESS) { returnData.code SUCCESS;//正确的订单处理 } else { returnData.code FAILD;//错误的订单处理 returnData.message 验证失败; } // 省略日志落盘App_Data/TenPayNotify/yyyyMMdd/... return Json(returnData); }回调处理链路的三个核心动作解密 验签TenPayNotifyHandler从HttpContext读取微信通知的原始请求头与请求体DecryptGetObjectAsyncOrderReturnJson自动完成 AEAD_AES_256_GCM 解密与平台证书验签一次性得到结构化的OrderReturnJson和VerifySignSuccess标记。其实现见 TenPayNotifyHandler.cs同时支持微信平台证书与国密 SM4 两种加密类型参数isPublicKey用于区分“使用微信支付公钥”与“使用平台证书”两种验签模式见 TenPayNotifyHandler.cs 的类定义。SDK 还提供了一组扩展方法如DecryptPayNotifyAsync可进一步简化调用见 TenPayNotifyHandlerExtensions.cs。业务判断只有VerifySignSuccess true trade_state SUCCESS时才认为交易真正成功此时才能进行数据库操作发货、改单状态等。示例还演示了把out_trade_no → transaction_id存入内存对照表TradeNumberToTransactionIdTenPayApiV3Controller.cs供后续退款接口使用生产环境应落库并考虑分布式缓存。返回规定格式必须返回 HTTP 200 且 Body 为{code: SUCCESS, message: OK}否则微信会按失败重试推送重试间隔逐渐拉长。回调中还应记录审计日志——示例将通知内容按天写入App_Data/TenPayNotify/目录下的文本文件。提示Native 支付的回调地址设置位置位于微信支付后台 产品中心 开发配置 Native 支付回调链接官方文档原文提示。回调接口必须部署在公网可访问的 HTTPS 域名下。六、回调之后订单查询、关闭与退款回调只覆盖“支付成功”这一条路径实际项目中还需要处理超时、取消、查询对账等场景。SDK 的BasePayApis提供了配套接口示例 Controller 中均有对应端点TenPayApiV3Controller.cs场景SDK 方法说明按商户订单号查询OrderQueryByOutTradeNoAsync(QueryRequestData)out_trade_no与transaction_id二选一查询订单状态按微信支付订单号查询OrderQueryByTransactionIdAsync(QueryRequestData)用transaction_id反查订单关闭订单CloseOrderAsync(CloseRequestData)用户长时间未扫码时关闭预支付单避免订单挂起申请退款RefundAsync(RefundRequestData)依赖回调中记录的transaction_id退款结果经RefundNotifyUrl回调通知其中订单查询端点在示例中演示了两种QueryRequestData构造方式并以 JSON 返回查询结果退款端点则演示了先查TradeNumberToTransactionId再调用RefundAsync的完整链路。更完整的回调与退款说明可参考仓库文档 callback.md 与 refund.md。七、安全与工程实践要点结合示例代码与 SDK 实现Native 支付落地时建议关注以下实践均来自仓库中可验证的实现与注释响应必须验签下单结果VerifySignSuccess与回调通知都必须验签通过才可使用示例在两个环节都做了该检查未通过时不要生成二维码、不要变更订单状态。以trade_state为准即使验签成功也需确认trade_state SUCCESS。回调可能多次重试订单状态更新需做幂等处理。订单号唯一性示例注释明确提示out_trade_no演示用“商户号 时间戳 随机串”高并发场景需增加去重检查保证同一商户号下唯一。订单有效期通过time_expire控制二维码过期示例为 1 小时过期后应引导用户重新下单而不是复用旧code_url。前端只展示、不确认二维码页面img src...NativePayCode只负责展示支付是否成功一律以服务端回调 订单查询为准不能依赖用户“支付成功”的前端跳转。可审计日志回调处理中将原始通知内容持久化示例落盘到App_Data/TenPayNotify/便于对账与故障排查退款、关单等操作同样建议留痕。配置与证书BasePayApis要求设置EncryptionType并需配置 APIv3 密钥、商户证书或平台公钥模式ISenparcWeixinSettingForTenpayV3相关配置项可在 register.md 与 install.md 中查看注册流程。八、小结WeiXinMPSDK 将微信支付 V3 的 Native 支付收敛为一条很短的调用链TransactionsRequestData组装订单参数 →BasePayApis.NativeAsync签名下单并验签 →QrCodeHelper把code_url变成 PNG 二维码 → 前端img展示 →TenPayNotifyHandler在notify_url端点完成回调解密、验签与订单确认。示例项目 Senparc.Weixin.Sample.TenPayV3 完整演示了该链路可直接作为 PC 网页与线下收银台扫码支付的落地参考核心 SDK 实现位于 Senparc.Weixin.TenPayV3 包中支持 .NET 8 / .NET 10 多目标框架。赞分享后端即时通讯金融科技【免费下载链接】WeiXinMPSDK微信全平台 .NET SDK Senparc.Weixin for C#支持 .NET Framework 及 .NET Core、.NET 10.0。已支持微信公众号、小程序、小游戏、微信支付、企业微信/企业号、开放平台、JSSDK、微信周边等全平台。 WeChat SDK for C#.项目地址https://gitcode.com/gh_mirrors/we/WeiXinMPSDK点击查看免费下载相关推荐WeiXinMPSDK 微信支付 V3 Native 扫码支付实战下单、二维码生成与回调验签全流程WeiXinMPSDK 微信支付 V3 Native 扫码支付实战下单、二维码生成与回调验签全流程 本文围绕 WeiXinMPSDKSenparc.Weix后端即时通讯金融科技RedisInsight战略转型从命令行工具到数据资产治理平台的技术范式演进RedisInsight战略转型从命令行工具到数据资产治理平台的技术范式演进 RedisInsight作为Redis官方推出的现代化GUI管理工具正在重新定后端即时通讯金融科技WeiXinMPSDK 微信 Native 支付实战指南从付款码 URL 签名、二维码生成到回调统一下单WeiXinMPSDK 微信 Native 支付实战指南从付款码 URL 签名、二维码生成到回调统一下单 Native 支付用于线下或微信环境以外的支付场后端即时通讯金融科技上一篇原神帧率解锁终极指南3步告别60帧限制让高刷显示器火力全开下一篇一个内核驱动让所有手柄都能畅玩3A大作ViGEmBus虚拟手柄驱动上手指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考