Added payment gateway ledger service to payments feature

2026-06-02 23:44:45 +02:00
parent 5ab2d29aac
commit 0ed04211bf
30 changed files with 3420 additions and 256 deletions
@@ -1,86 +1,158 @@
 using LiteCharms.Features.Hasher;
+using LiteCharms.Features.Hasher.Configuration;
 using LiteCharms.Features.MidrandBooks.Orders;
+using LiteCharms.Features.MidrandBooks.Payments.Models;

 namespace LiteCharms.Features.MidrandBooks.Payments.Events.Handlers;

-public sealed class PayfastPaymentConfirmationReceivedEventHandler(IServiceProvider services, ILogger<PayfastPaymentConfirmationReceivedEvent> logger) : 
+public sealed class PayfastPaymentConfirmationReceivedEventHandler(IServiceProvider services, IOptions<HasherSettings> hasherOptions, ILogger<PayfastPaymentConfirmationReceivedEvent> logger) : 
    INotificationHandler<PayfastPaymentConfirmationReceivedEvent>
 {
+    private readonly HasherSettings hasherSettings = hasherOptions.Value;
+
    public async ValueTask Handle(PayfastPaymentConfirmationReceivedEvent notification, CancellationToken cancellationToken)
    {
        await using var scope = services.CreateAsyncScope();
+        var hashService = scope.ServiceProvider.GetRequiredService<HashService>();
+        var orderService = scope.ServiceProvider.GetRequiredService<OrderService>();
+        var paymentService = scope.ServiceProvider.GetRequiredService<PaymentService>();
+        var payfastService = scope.ServiceProvider.GetRequiredService<PayfastService>();

-        PaymentService paymentService = scope.ServiceProvider.GetRequiredService<PaymentService>();
-        OrderService orderService = scope.ServiceProvider.GetRequiredService<OrderService>();
-        HashService hashService = scope.ServiceProvider.GetRequiredService<HashService>();
+        var payload = notification.Payload ?? throw new Exception("Payload metadata context context is null.");

-        var hashResult = hashService.DecodeLongIdHash(notification.Payload?.MPaymentId!);
-        if (hashResult.IsFailed)
+        var dict = payload.ToParamDictionary();
+        var localSignature = PayfastService.GenerateSignature(dict, hasherSettings.PayfastPassphrase);
+
+        if(localSignature.IsFailed)
+            throw new Exception("Failed to generate local signature for incoming webhook payload.");
+
+        if (!string.Equals(localSignature.Value, payload.Signature, StringComparison.OrdinalIgnoreCase))
        {
-            logger.LogError("Failed to decode payment ID hash: {Hash}. Errors: {Errors}", notification.Payload?.MPaymentId, string.Join(", ", hashResult.Errors.Select(e => e.Message)));
-            throw new Exception($"Failed to decode payment ID hash: {notification.Payload?.MPaymentId}.");
-        }
+            logger.LogCritical("Incoming webhook signature verification failed. Possible payload tampering.");

-        var orderResult = await orderService.GetOrderAsync(hashResult.Value, cancellationToken);
-        if (orderResult.IsFailed)
-        {
-            logger.LogError("Failed to retrieve order for payment ID: {PaymentId}. Errors: {Errors}", notification.Payload?.MPaymentId, string.Join(", ", orderResult.Errors.Select(e => e.Message)));
-            throw new Exception($"Failed to retrieve order for payment ID: {notification.Payload?.MPaymentId}.");
-        }
-
-        var paymentResult = await paymentService.GetOrderPaymentAsync(orderResult.Value.CustomerId, cancellationToken);
-        if (paymentResult.IsFailed)
-        {
-            logger.LogError("Failed to retrieve payment for order ID: {OrderId}. Errors: {Errors}", orderResult.Value.Id, string.Join(", ", paymentResult.Errors.Select(e => e.Message)));
-            throw new Exception($"Failed to retrieve payment for order ID: {orderResult.Value.Id}.");
-        }
-
-        var isAlreadyProcessed = await paymentService.HasLedgerEntryAsync(orderResult.Value.Id, paymentResult.Value.Id, 1, cancellationToken);
-
-        if (isAlreadyProcessed.IsFailed)
-        {
-            logger.LogError("Failed to check existing ledger entry for order ID: {OrderId} and payment ID: {PaymentId}. Errors: {Errors}", orderResult.Value.Id, paymentResult.Value.Id, string.Join(", ", isAlreadyProcessed.Errors.Select(e => e.Message)));
-            throw new Exception($"Failed to check existing ledger entry for order ID: {orderResult.Value.Id} and payment ID: {paymentResult.Value.Id}.");
-        }
-
-        if (isAlreadyProcessed.Value)
-        {
-            logger.LogInformation("Payment confirmation for payment ID: {PaymentId} has already been processed. Skipping.", notification.Payload?.MPaymentId);
            return;
        }

-        var ledgerResult = await paymentService.WriteLedgerEntryAsync(new Models.CreateLedgerEntry
+        var hashResult = hashService.DecodeLongIdHash(payload.MerchantPaymentId!);
+
+        if (hashResult.IsFailed) throw new Exception("Failed to decode application tracking hash key identifier.");
+
+        var orderResult = await orderService.GetOrderAsync(hashResult.Value, cancellationToken);
+
+        if (orderResult.IsFailed) throw new Exception("Target system order entity context cannot be traced.");
+
+        var paymentResult = await paymentService.GetOrderPaymentAsync(orderResult.Value.Id, cancellationToken);
+
+        if (paymentResult.IsFailed) throw new Exception("Target payment ledger entity cannot be resolved.");
+
+        decimal.TryParse(payload.AmountGross, CultureInfo.InvariantCulture, out var gross);
+        decimal.TryParse(payload.AmountFee, CultureInfo.InvariantCulture, out var fee);
+        decimal.TryParse(payload.AmountNet, CultureInfo.InvariantCulture, out var net);
+        string status = payload.PaymentStatus ?? "UNKNOWN";
+
+        var isAlreadyProcessed = await paymentService.HasLedgerEntryAsync(orderResult.Value.Id, paymentResult.Value.Id, cancellationToken);
+
+        if (isAlreadyProcessed.Value)
+        {
+            logger.LogWarning("Webhook reference token '{Ref}' already verified. Skipping validation routines.", payload.MerchantPaymentId);
+
+            return;
+        }
+
+        if (notification.PerformBackgroundChecks)
+        {
+            var isHostValid = await payfastService.ValidateReferrerIpAsync(notification.RemoteIpAddress!, cancellationToken);
+
+            if (isHostValid.IsFailed) 
+                throw new Exception("Security validation exception: Webhook packet source address failed cluster validation checks.");
+
+            if (!isHostValid.Value)
+                throw new Exception("Security validation exception: Webhook packet source address failed cluster validation checks.");
+
+            var isAmountValid = payfastService.ValidatePaymentAmount(orderResult.Value.Total, payload.AmountGross);
+
+            if (!isAmountValid.Value) 
+                throw new Exception("Security validation exception: Transaction cost variance bounds breached.");
+
+            var paramList = new List<string>();
+
+            foreach (var kvp in dict)
+            {
+                if (!string.IsNullOrEmpty(kvp.Value))
+                {
+                    string encoded = HttpUtility.UrlEncode(kvp.Value.Trim());
+
+                    string safeValue = PayfastService.PercentEncodingRegex.Replace(encoded, m => m.Value.ToLowerInvariant());
+                    paramList.Add($"{kvp.Key}={safeValue}");
+                }
+            }
+
+            string rawParamString = string.Join("&", paramList);
+
+            var serverConfirmation = await payfastService.ValidateServerConfirmationAsync(rawParamString, isSandbox: true, cancellationToken);
+
+            if (serverConfirmation.IsFailed) 
+                throw new Exception("Security validation exception: Payfast central handshake server rejected payload legitimacy."); 
+        }
+
+        await payfastService.WriteLedgerEntryAsync(new CreateGatewayLedgerEntry
        {
-            CustomerId = orderResult.Value.CustomerId,
            OrderId = orderResult.Value.Id,
            PaymentId = paymentResult.Value.Id,
-            Status = LedgerStatuses.Received,
-            PaymentGatewayId = 1,
-            PaymentGatewayReference = notification.CorrelationId,
+            MerchantPaymentId = payload.MerchantPaymentId!,
+            PayfastPaymentId = payload.PaymentId,
+            CustomerEmail = payload.EmailAddress,
+            AmountFee = fee,
+            AmountGross = gross,
+            AmountNet = net,
+            PaymentStatus = status,            
        }, cancellationToken);

-        if (ledgerResult.IsFailed)
+        if (status.Equals("COMPLETE", StringComparison.OrdinalIgnoreCase))
        {
-            logger.LogError("Failed to write ledger entry for payment ID: {PaymentId}. Errors: {Errors}", notification.Payload?.MPaymentId, string.Join(", ", ledgerResult.Errors.Select(e => e.Message)));
-            throw new Exception($"Failed to write ledger entry for payment ID: {notification.Payload?.MPaymentId}.");   
-        }
+            var ledgerWriteResult = await paymentService.WriteLedgerEntryAsync(new CreateLedgerEntry
+            {
+                OrderId = orderResult.Value.Id,
+                PaymentId = paymentResult.Value.Id,
+                PaymentGatewayReference = payload.PaymentId!,
+                Status = LedgerStatuses.Completed,
+                CustomerId = orderResult.Value.CustomerId,
+            }, cancellationToken);

-        var paymentCompletedResult = await paymentService.CompletePaymentAsync(paymentResult.Value.Id, PaymentStatuses.Paid, cancellationToken);
-        if (paymentCompletedResult.IsFailed)
+            if (ledgerWriteResult.IsFailed)
+                throw new Exception("Failed to write ledger entry for payment confirmation.");
+
+            var completePaymentResult = await paymentService.CompletePaymentAsync(paymentResult.Value.Id, PaymentStatuses.Paid, cancellationToken);
+
+            if (completePaymentResult.IsFailed)
+                throw new Exception("Failed to update payment status to 'Paid' for payment confirmation.");
+
+            var updateOrderResult = await orderService.UpdateOrderStatusAsync(orderResult.Value.Id, OrderStatus.Completed, cancellationToken);
+
+            if (updateOrderResult.IsFailed)
+                throw new Exception("Failed to update order status to 'Completed' for payment confirmation.");
+
+            logger.LogInformation("Order payment verified secure and cleared successfully.");
+        }
+        else
        {
-            logger.LogError("Failed to complete payment for order ID: {OrderId}. Errors: {Errors}", orderResult.Value.Id, string.Join(", ", paymentCompletedResult.Errors.Select(e => e.Message)));
-            throw new Exception($"Failed to complete payment for order ID: {orderResult.Value.Id}.");
+            LedgerStatuses ledgerStatus;
+
+            if (status.Equals("CANCELLED", StringComparison.OrdinalIgnoreCase))
+                ledgerStatus = LedgerStatuses.Cancelled;
+            else
+                ledgerStatus = LedgerStatuses.Failed;
+
+            var ledgerWriteResult = await paymentService.WriteLedgerEntryAsync(new CreateLedgerEntry
+            {
+                OrderId = orderResult.Value.Id,
+                PaymentId = paymentResult.Value.Id,
+                PaymentGatewayReference = payload.PaymentId!,
+                Status = ledgerStatus,
+                CustomerId = orderResult.Value.CustomerId,
+            }, cancellationToken);
+
+            logger.LogInformation("Webhook validation pipeline passed checks successfully, logged entry to ledger with status: {Status}", status);
        }
-
-        var orderCompletedResult = await orderService.UpdateOrderStatusAsync(orderResult.Value.Id, OrderStatus.Completed, cancellationToken);
-        if (orderCompletedResult.IsFailed)
-        {
-            logger.LogError("Failed to update order status to Completed for order ID: {OrderId}. Errors: {Errors}", orderResult.Value.Id, string.Join(", ", orderCompletedResult.Errors.Select(e => e.Message)));
-            throw new Exception($"Failed to update order status to Completed for order ID: {orderResult.Value.Id}.");
-        }
-
-        logger.LogInformation("Received Payfast payment confirmation for payment ID: {PaymentId}", notification.Payload?.MPaymentId);
-
-        // TODO: Publish MediatR notifications or queue downstream Quartz jobs (Discord, Shipping, Customer Email, Royalties)
    }
 }
@@ -1,5 +1,5 @@
 using LiteCharms.Features.Abstractions;
-using LiteCharms.Features.Models;
+using LiteCharms.Features.MidrandBooks.Payments.Models;

 namespace LiteCharms.Features.MidrandBooks.Payments.Events;

@@ -9,14 +9,19 @@ public sealed class PayfastPaymentConfirmationReceivedEvent : EventBase, IEvent

    public PayfastWebhookPayload? Payload { get; set; }

+    public string? RemoteIpAddress { get; set; }
+
+    public bool PerformBackgroundChecks { get; set; }
+
    public PayfastPaymentConfirmationReceivedEvent() { }

-    private PayfastPaymentConfirmationReceivedEvent(PayfastWebhookPayload? payload, string paymentId)
+    private PayfastPaymentConfirmationReceivedEvent(PayfastWebhookPayload? payload, string paymentId, bool performBackgroundChecks = true)
    {
        Payload = payload;
        CorrelationId = paymentId;
+        PerformBackgroundChecks = performBackgroundChecks;
    }

-    public static PayfastPaymentConfirmationReceivedEvent Create(PayfastWebhookPayload? payload, string paymentId) =>
-        new(payload, paymentId);
+    public static PayfastPaymentConfirmationReceivedEvent Create(PayfastWebhookPayload? payload, string paymentId, bool performBackgroundChecks = true) =>
+        new(payload, paymentId, performBackgroundChecks);
 }