.NET 第三方支付集成 Paylinks 使用详解：开发者必备指南

什么是 Paylinks？.NET 支付集成利器

Paylinks 是一套基于现代 .NET 平台开发的第三方支付 SDK，由开源社区维护，旨在简化开发者接入主流第三方支付渠道（如支付宝、微信支付）的流程。该 SDK 支持跨平台运行，并设计为可用于多商户场景，非常适合电商平台、SaaS 系统、后台服务等场景中快速集成支付能力的需求。

Paylinks 的核心特点包括：

跨平台支持：兼容不同操作系统与 .NET 版本。
多商户能力：支持在同一系统中管理多个商户支付配置。
简化集成：封装了支付签名、加密、参数组合等底层细节。
统一 API 设计：为不同支付渠道提供一致的调用体验。

Paylinks 的源码托管在 GitHub/Gitee，开发者可以根据具体需求下载查看完整示例和文档。

Paylinks GitHub 地址：https://github.com/essensoft/paylinks
Paylinks Gitee 地址：https://gitee.com/essensoft/paylinks

Paylinks 支持的支付渠道与场景

Paylinks SDK 当前主要围绕两个主流国内支付渠道提供封装支持：

支付宝支付（Alipay）
微信支付（WeChat Pay）

适配这些渠道的各种支付方式（如扫码支付、网页支付等），并提供统一的调用入口和标准化配置结构，便于开发者快速实现支付下单、结果通知处理、订单查询等常用功能。

支持场景示例可包括：

电商平台支付结算
多商户 SaaS 应用支付功能
订单管理后台自动化支付处理
移动端与桌面端统一支付接入

如何安装 Paylinks

在你的 .NET 项目中使用 NuGet 包管理器安装相关 SDK 组件，例如：

dotnet add package Essensoft.Paylinks.Alipay.Client
dotnet add package Essensoft.Paylinks.Alipay.Payments

dotnet add package Essensoft.Paylinks.WeChatPay.Client
dotnet add package Essensoft.Paylinks.WeChatPay.Payments

这些包分别负责提供支付宝和微信支付的客户端与支付 API 功能。

在 ASP.NET Core 中配置 Paylinks

Paylinks 使用标准的 ASP.NET Core 依赖注入（DI）和 Options 模式 进行配置，使得集成过程与现代 .NET 应用一致。

添加服务与依赖注入

在 Program.cs 或 Startup.cs 中注册支付客户端：

builder.Services.AddAlipayClient(options =>
{
    options.AppId = Configuration["Alipay:AppId"];
    options.MerchantPrivateKey = Configuration["Alipay:MerchantPrivateKey"];
    options.AlipayPublicKey = Configuration["Alipay:AlipayPublicKey"];
    options.NotifyUrl = Configuration["Alipay:NotifyUrl"];
});

builder.Services.AddWeChatPayClient(options =>
{
    options.AppId = Configuration["WeChatPay:AppId"];
    options.MchId = Configuration["WeChatPay:MchId"];
    options.ApiV3Key = Configuration["WeChatPay:ApiV3Key"];
    options.NotifyUrl = Configuration["WeChatPay:NotifyUrl"];
});

在其他类中通过构造器注入服务实例：

public class PaymentService
{
    private readonly IAlipayClient _alipayClient;
    private readonly IWeChatPayClient _weChatPayClient;

    public PaymentService(IAlipayClient alipayClient, IWeChatPayClient weChatPayClient)
    {
        _alipayClient = alipayClient;
        _weChatPayClient = weChatPayClient;
    }
}

这种方式让配置和调用清晰可控，与 .NET 主流应用体系兼容。

实战示例：创建支付订单

支付宝下单示例

构建请求模型，并发送支付请求：

var model = new AlipayTradePreCreateBodyModel
{
    OutTradeNo = Guid.NewGuid().ToString("N"),
    TotalAmount = "0.01",
    Subject = "商品支付",
    NotifyUrl = "https://yourdomain.com/alipay/notify"
};

var request = new AlipayTradePreCreateRequest();
request.SetBodyModel(model);

var response = await _alipayClient.ExecuteAsync(request);
if (response.IsSuccessful)
{
    // 获取二维码链接或支付信息
    var qrCode = response.QrCode;
}

该流程完成统一订单创建并获取支付凭证，可用于前端展示二维码或跳转支付。

微信支付下单示例

类似地，创建微信支付订单：

var model = new WeChatPayNativeOrderRequest
{
    Body = "商品支付",
    OutTradeNo = Guid.NewGuid().ToString("N"),
    TotalFee = 1, // 单位：分
    NotifyUrl = "https://yourdomain.com/wechatpay/notify"
};

var response = await _weChatPayClient.ExecuteAsync(model);
if (response.IsSuccessful)
{
    var codeUrl = response.CodeUrl;
}

获取 CodeUrl 后可用于生成二维码供用户扫二维码支付。

支付成功回调与通知处理

第三方支付平台在用户完成支付后会发送回调通知，开发者需要实现相应路由来处理这些通知信息：

[HttpPost]
public async Task<IActionResult> AlipayNotify()
{
    var notifyRequest = Request.Form.ToAlipayNotifyRequest();
    var result = await _alipayClient.ExecuteAsync(notifyRequest);
    if (result.IsSuccess)
    {
        // 处理订单状态更新
    }
    return Content("success");
}

同样微信支付回调需要按照微信回调协议解析与验证，实现订单状态变更、签名校验逻辑等。

开发注意事项

安全配置管理：将密钥、证书、API Key 等敏感信息通过环境变量或安全配置方式管理，避免硬编码。
异常与日志处理：在实际生产环境中，应对所有请求和响应加上日志与异常捕获，便于排查支付异常。
订单唯一 ID 设计：订单号要保证全局唯一，以免在支付平台造成重复订单冲突。
多商户支持逻辑：如需支持多个商户账户，可结合 IOptionsMonitor 动态获取不同商户配置。

总结与建议

Paylinks 是一款现代 .NET 支付集成 SDK，通过封装底层复杂逻辑，使开发者可以更专注于业务而非支付协议细节。它适用于各种 .NET 项目，特别是需要快速扩展支付功能的系统中。开发者在使用时，可以结合项目架构灵活配置依赖注入与通知处理机制，确保支付流程安全完整。通过 Paylinks 这样的工具，支付功能的接入成本大大降低，有助于加速项目上线流程，提高开发效率。