DotNetCore.SKIT.FlurlHttpClient.Wechat 微信支付回调验签实现指南

在开发微信支付功能时，正确处理支付回调通知是确保交易安全的重要环节。本文将详细介绍如何使用 DotNetCore.SKIT.FlurlHttpClient.Wechat 库实现微信支付回调的验签功能。

核心概念解析

在微信支付体系中，存在两种关键证书：

1. 商户证书：由商户自己生成，用于向微信支付服务器发起请求时的身份验证
2. 平台证书：由微信支付平台提供，用于验证微信支付回调通知的真实性

配置微信支付服务

首先需要在项目中配置微信支付服务，以下是完整的配置示例：

// 初始化证书管理器
var manager = new InMemoryCertificateManager();

// 配置微信支付选项
var options = new WechatTenpayClientOptions()
{
    MerchantId = "你的商户号",
    MerchantV3Secret = "APIv3密钥",
    MerchantCertificateSerialNumber = "商户证书序列号",
    MerchantCertificateKey = File.ReadAllText(
        Path.Combine(AppDomain.CurrentDomain.BaseDirectory, 
        "WeChatPayConfigLibrary", "apiclient_key.pem")),
    PlatformCertificateManager = manager
};

// 创建微信支付客户端
var client = new WechatTenpayClient(options);

// 获取并解密平台证书
var response = await client.ExecuteQueryCertificatesAsync(
    new QueryCertificatesRequest() { AlgorithmType = "RSA" });
response = client.DecryptResponseSensitiveProperty(response);

// 将平台证书添加到管理器
foreach (var certificate in response.CertificateList)
{
    manager.AddEntry(CertificateEntry.Parse("RSA", certificate));
}

// 注册为单例服务
builder.Services.AddSingleton(
    WechatTenpayClientBuilder.Create(options).Build());

实现回调验签

在控制器中处理微信支付回调时，需要完成以下步骤：

1. 获取请求头中的验证信息
2. 读取请求体内容
3. 验证签名
4. 处理回调事件

[HttpPost]
public async Task<IActionResult> ReceiveMessage()
{
    try
    {
        // 获取验证头信息
        var nonce = Request.Headers["Wechatpay-Nonce"].ToString();
        var serialNumber = Request.Headers["Wechatpay-Serial"].ToString();
        var signature = Request.Headers["Wechatpay-Signature"].ToString();
        var timestamp = Request.Headers["Wechatpay-Timestamp"].ToString();
        
        // 读取请求体
        using var reader = new StreamReader(Request.Body, Encoding.UTF8);
        string content = await reader.ReadToEndAsync();
        
        // 验证签名
        ErroredResult valid = client.VerifyEventSignature(
            timestamp, nonce, content, signature, serialNumber);
        
        if (!valid.Result)
        {
            // 记录验证失败原因
            Log.Information("验签失败原因：{Error}", valid.Error);
            return BadRequest();
        }
        
        // 解析回调事件
        var callbackModel = client.DeserializeEvent(content);
        var eventType = callbackModel.EventType?.ToUpper();
        
        // 处理不同类型的事件
        switch (eventType)
        {
            case "TRANSACTION.SUCCESS":
                // 处理支付成功逻辑
                var transaction = client.DecryptEventResource<TransactionResource>(callbackModel);
                Log.Information("支付成功，订单号：{OutTradeNo}", transaction.OutTradeNumber);
                break;
                
            case "REFUND.SUCCESS":
                // 处理退款成功逻辑
                var refund = client.DecryptEventResource<RefundResource>(callbackModel);
                Log.Information("退款成功，退款单号：{OutRefundNo}", refund.OutRefundNumber);
                break;
                
            default:
                Log.Warning("未知事件类型：{EventType}", eventType);
                break;
        }
        
        return Ok();
    }
    catch (Exception ex)
    {
        Log.Error(ex, "处理微信支付回调时发生异常");
        return StatusCode(500);
    }
}

常见问题解决方案

1. 平台证书解密失败：

   • 确保在获取平台证书后调用 DecryptResponseSensitiveProperty 方法解密
   • 检查 APIv3 密钥是否正确

2. 验签失败：

   • 确认时间戳是否在有效期内（通常为5分钟内）
   • 检查请求体是否被修改过
   • 验证使用的平台证书是否最新

3. 证书混淆：

   • 商户证书以 -----BEGIN KEY----- 开头
   • 平台证书以 -----BEGIN CERTIFICATE----- 开头

通过以上实现，开发者可以安全可靠地处理微信支付回调通知，确保交易数据的真实性和完整性。在实际项目中，建议将回调处理逻辑封装为独立服务，并添加适当的日志记录和异常处理机制。