BiuPay.Net 2.7.0

# BiuPay.Net

BiuPay.Net 是一个用于与 BiuPay 支付系统集成的 .NET 客户端库。

## 安装

通过 NuGet 包管理器安装：

```bash
dotnet add package BiuPay.Net

配置

1. 添加配置

在 appsettings.json 中添加 BiuPay 配置：

{
  "BiuPay": {
    "Url": "https://xxxxx.com/",
    "ClientId": "your_client_id",
    "ClientSecret": "your_client_secret",
    "CallbackSecret": "your_callback_secret"
  }
}

2. 服务注册

在 Program.cs 或 Startup.cs 中注册 BiuPay 服务：

using BiuPay.Net;

var builder = WebApplication.CreateBuilder(args);

// 添加配置
builder.Services.AddBiuPay(builder.Configuration);

// 或者手动配置
var biuPayConfig = new BiuPayConfig
{
    Url = "https://xxxxx.com/",
    ClientId = "your_client_id",
    ClientSecret = "your_client_secret",
    CallbackSecret = "your_callback_secret"
};
builder.Services.AddBiuPay(biuPayConfig);

使用方法

依赖注入

在你的服务中注入 IBiuPayClient：

public class PaymentService
{
    private readonly IBiuPayClient _biuPayClient;

    public PaymentService(IBiuPayClient biuPayClient)
    {
        _biuPayClient = biuPayClient;
    }
}

发起扣款请求

var request = new DeductRequest
{
    Amount = 10.50m,
    Currency = "ZMW",
    BizId = "order_123456",
    BizType = "payment",
    CallbackUrl = "https://your-domain.com/callback",
    CustomerName = "John Doe",
    CustomerAccount = "123456789",
    PaymentChannel = PaymentChannelEnum.Zamtel
};

var response = await _biuPayClient.DeductAsync(request);

if (response.Status == PaymentOrderStatus.Init)
{
    // 扣款请求已成功创建
    Console.WriteLine($"Transaction ID: {response.TransactionId}");
}

查询交易状态

var queryRequest = new QueryTransactionRequest
{
    BizId = "order_123456"
};

var transaction = await _biuPayClient.QueryTransactionAsync(queryRequest);

Console.WriteLine($"Amount: {transaction.Amount}");
Console.WriteLine($"Status: {transaction.Status}");

配置参数说明

支付渠道

支持以下支付渠道：

• PaymentChannelEnum.Zamtel - Zamtel 支付

交易状态

• PaymentOrderStatus.Init - 初始状态
• PaymentOrderStatus.Pending - 处理中
• PaymentOrderStatus.Success - 成功
• PaymentOrderStatus.Failed - 失败

回调处理(验签)

验签前置配置：启用原始 Body 缓冲

为确保回调验签正确，可以使用中间件捕获原始 Body 并启用缓冲，只对回调路径开启，避免全局性能影响。

1. 创建中间件

using System.Text;

public class CaptureRawBodyMiddleware
{
    private readonly RequestDelegate _next;

    public CaptureRawBodyMiddleware(RequestDelegate next)
    {
        _next = next;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        context.Request.EnableBuffering(bufferThreshold: 1024 * 1024, bufferLimit: 5 * 1024 * 1024);

        using var reader = new StreamReader(
            context.Request.Body,
            Encoding.UTF8,
            detectEncodingFromByteOrderMarks: false,
            leaveOpen: true);

        var rawBody = await reader.ReadToEndAsync();
        context.Request.Body.Position = 0;

        context.Items["RawBody"] = rawBody;

        await _next(context);
    }
}

2. 注册中间件

在 Program.cs 中，确保中间件在 add.UseEndpoints 之前注册：

var app = builder.Build();

......

// 对回调路径启用启用缓冲区
app.UseWhen(
    context => context.Request.Path.StartsWithSegments("/callback"), // 使用你的回调 Path
    appBuilder => appBuilder.UseMiddleware<CaptureRawBodyMiddleware>());

......

app.UseRouting();
app.UseEndpoints(endpoints =>
{
    endpoints.MapControllers();
});
app.Run();

3. 接受回调并验证签名

确保你的回调端点能够处理 BiuPay 发送的支付结果通知。回调 URL 需要在发起支付请求时指定。

[HttpPost("callback")]
[AllowAnonymous]  // 需要允许匿名访问, 使用SDK提供的验签工具实现验签
public async Task<IActionResult> Callback()
{
    string rawRequestBody;
    using var reader = new StreamReader(Request.Body, Encoding.UTF8);
    rawRequestBody = await reader.ReadToEndAsync();
    Request.Body.Position = 0;

    var clientId = Request.Headers[BiuPay.Net.CallbackVerifier.HeaderClientId].FirstOrDefault();
    var timestamp = Request.Headers[BiuPay.Net.CallbackVerifier.HeaderTimestamp].FirstOrDefault();
    var signature = Request.Headers[BiuPay.Net.CallbackVerifier.HeaderSignature].FirstOrDefault();

    if (string.IsNullOrWhiteSpace(clientId) ||
        string.IsNullOrWhiteSpace(timestamp) ||
        string.IsNullOrWhiteSpace(signature))
    {
        return Unauthorized("Missing required headers");
    }

    var httpMethod = Request.Method;
    var callbackUrl = "https://your-domain.com/callback";    // 这里传入发起请求时传入的 CallbackUrl

    var isValid = BiuPay.Net.CallbackVerifier.Verify(
        clientId,
        timestamp,
        signature,
        httpMethod,
        callbackUrl,
        rawRequestBody,
        callbackSecret);

    if (!isValid)
        return Unauthorized("Signature verification failed");

    var callbackRequest = JsonSerializer.Deserialize<QueryTransactionResponse>(rawRequestBody, JsonSerializerOptions.Web);
    // ... 执行业务逻辑 ...

    return Ok("OK"); // 必须返回 HttpCode 200 + 内容 "OK"，否则支付网关会持续重试
}

4. 注意事项

• 只对回调路径启用缓冲，避免占用过多内存。
• 可通过 bufferThreshold 和 bufferLimit 控制内存和临时文件使用。
• 返回 200 OK + 内容 "OK" 表示业务端成功接收回调，否则支付网关会重试。