Payment 支付域手册

Bitzsoft.Integrations.Payment            ← 抽象层（接口 + DTO + Result + Exception）
├── Bitzsoft.Integrations.Payment.Alipay     ← 支付宝（RSA2 签名）
├── Bitzsoft.Integrations.Payment.WeChatPay  ← 微信支付（APIv3，RSA-SHA256 + AES-256-GCM）
├── Bitzsoft.Integrations.Payment.Stripe     ← Stripe（Bearer + Webhook HMAC）
└── Bitzsoft.Integrations.Payment.All        ← 聚合包（按配置节自动注册）

public interface IPaymentProvider
{
    string Code { get; }

    Task<PaymentResult<PaymentOrderResult>> CreateOrderAsync(
        PaymentOrderRequest request, CancellationToken ct = default);

    Task<PaymentResult<PaymentStatusResult>> QueryStatusAsync(
        string outTradeNo, CancellationToken ct = default);

    Task<PaymentResult> CloseOrderAsync(
        string outTradeNo, CancellationToken ct = default);

    Task<PaymentResult<RefundResult>> RefundAsync(
        RefundRequest request, CancellationToken ct = default);

    Task<PaymentResult<CallbackVerificationResult>> VerifyCallbackAsync(
        CallbackPayload payload, CancellationToken ct = default);
}

public sealed class PaymentResult<T>
{
    public bool IsSuccess { get; init; }
    public T? Data { get; init; }              // 成功时有值
    public string? ErrorCode { get; init; }     // 供应商原始错误码
    public string? ErrorMessage { get; init; }  // 错误消息

    public static PaymentResult<T> Success(T data);
    public static PaymentResult<T> Fail(string errorCode, string errorMessage);
}

public enum PaymentScene  { App = 0, Web = 1, H5 = 2, Code = 3 }
public enum PaymentStatus { Pending = 0, Success = 1, Closed = 2, Refunded = 3, Failed = 4 }
public enum RefundStatus  { Pending = 0, Success = 1, Failed = 2, Abnormal = 3 }

public interface IPaymentConfigProvider<TOptions> where TOptions : class
{
    TOptions Current { get; }
    string HttpClientName { get; }
}

public class CheckoutRouter(IIntegrationProviderResolver<IPaymentProvider> providers)
{
    public async Task PayAsync(string providerId, PaymentOrderRequest req)
    {
        var payment = providers.GetRequired(providerId);
        var result = await payment.CreateOrderAsync(req);
        if (!result.IsSuccess)
            throw new InvalidOperationException(result.ErrorMessage);
    }
}

CallbackPayload { Body, Headers, QueryString }
        │
        ├─ Alipay: 从 Body / QueryString 解析参数 → RSA2 验签 → 直接读取明文字段
        │
        ├─ WeChatPay: 从 Headers 取签名 → RSA-SHA256 验签 → AES-256-GCM 解密 resource.ciphertext
        │
        └─ Stripe: 从 Headers 取 Stripe-Signature → HMAC-SHA256 验签 → 直接读取明文 JSON
                    │
                    ▼
        CallbackVerificationResult { OutTradeNo, TradeNo?, PaidAmount, PaidAt?, Status, RawData }

public class PaymentException : IntegrationException
{
    public string ProviderName { get; }    // 如 "alipay"
    public string? ErrorCode { get; }      // 供应商原始错误码
    public string? ProviderMessage { get; } // 供应商原始错误消息
}

// 支付宝
builder.Services.AddBitzsoftAlipayPayment(builder.Configuration.GetSection("Alipay"));

// 微信支付
builder.Services.AddBitzsoftWeChatPayPayment(builder.Configuration.GetSection("WeChatPay"));

// Stripe
builder.Services.AddBitzsoftStripePayment(builder.Configuration.GetSection("Stripe"));

builder.Services.AddBitzsoftPaymentAll(builder.Configuration, "Payment");

{
  "Payment": {
    "Alipay":    { "AppId": "...", "AppPrivateKey": "...", "AlipayPublicKey": "..." },
    "WeChatPay": { "AppId": "...", "MchId": "...", "MchSerialNo": "...", "APIv3Key": "...", "PrivateKey": "...", "WeChatPayPublicKey": "..." },
    "Stripe":    { "SecretKey": "sk_live_xxx", "WebhookSecret": "whsec_xxx" }
  }
}

public class CheckoutService(IPaymentProvider payment)
{
    public async Task<string> CreateOrderAsync(string orderNo, long cents, string subject)
    {
        var result = await payment.CreateOrderAsync(new PaymentOrderRequest
        {
            OutTradeNo = orderNo,
            TotalAmount = cents,       // 分
            Subject = subject,
            Scene = PaymentScene.Web,
            ReturnUrl = "https://shop.example.com/return",
        });

        if (!result.IsSuccess)
            throw new InvalidOperationException(
                $"[{result.ErrorCode}] {result.ErrorMessage}");

        return result.Data!.PayUrl!;   // Web 场景返回跳转 URL
    }
}

public class RefundService(IPaymentProvider payment)
{
    public async Task RefundAsync(string orderNo, string refundNo, long cents)
    {
        var result = await payment.RefundAsync(new RefundRequest
        {
            OutTradeNo = orderNo,
            RefundNo = refundNo,
            RefundAmount = cents,
            Reason = "用户申请退款",
        });

        if (!result.IsSuccess || result.Data!.Status != RefundStatus.Success)
            throw new InvalidOperationException(result.ErrorMessage);
    }
}

var handler = new MockHttpMessageHandler();
services.AddHttpClient(nameof(AlipayPaymentProvider))
    .ConfigurePrimaryHttpMessageHandler(() => handler);

var result = await provider.QueryStatusAsync("ORDER_123");

Assert.False(result.IsSuccess);
Assert.Equal("ACQ.TRADE_NOT_EXIST", result.ErrorCode);