Merge pull request 'Added PayfastPaymentConfirmationReceivedEvent' (#57) from payments into master

Reviewed-on: #57

LiteCharms.Features.MidrandBooks/Payments/Events/Handlers/PayfastPaymentConfirmationReceivedEventHandler.cs

@@ -0,0 +1,81 @@
+using LiteCharms.Features.Hasher;
+using LiteCharms.Features.MidrandBooks.Orders;
+
+namespace LiteCharms.Features.MidrandBooks.Payments.Events.Handlers;
+
+public sealed class PayfastPaymentConfirmationReceivedEventHandler(PaymentService paymentService,
+    HashService hashService, OrderService orderService, ILogger<PayfastPaymentConfirmationReceivedEvent> logger) : 
+    INotificationHandler<PayfastPaymentConfirmationReceivedEvent>
+{
+    public async ValueTask Handle(PayfastPaymentConfirmationReceivedEvent notification, CancellationToken cancellationToken)
+    {
+        var hashResult = hashService.DecodeLongIdHash(notification.Payload?.MPaymentId!);
+        if (hashResult.IsFailed)
+        {
+            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}.");
+        }
+
+        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
+        {
+            CustomerId = orderResult.Value.CustomerId,
+            OrderId = orderResult.Value.Id,
+            PaymentId = paymentResult.Value.Id,
+            Status = LedgerStatuses.Received,
+            PaymentGatewayId = 1,
+            PaymentGatewayReference = notification.CorrelationId,
+        }, cancellationToken);
+
+        if (ledgerResult.IsFailed)
+        {
+            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 paymentCompletedResult = await paymentService.CompletePaymentAsync(paymentResult.Value.Id, PaymentStatuses.Paid, cancellationToken);
+        if (paymentCompletedResult.IsFailed)
+        {
+            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}.");
+        }
+
+        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)
+    }
+}

LiteCharms.Features.MidrandBooks/Payments/Events/PayfastPaymentConfirmationReceivedEvent.cs

@@ -0,0 +1,22 @@
+using LiteCharms.Features.Abstractions;
+using LiteCharms.Features.Models;
+
+namespace LiteCharms.Features.MidrandBooks.Payments.Events;
+
+public sealed class PayfastPaymentConfirmationReceivedEvent : EventBase, IEvent
+{
+    public string Name { get; set; } = nameof(PayfastPaymentConfirmationReceivedEvent);
+
+    public PayfastWebhookPayload? Payload { get; set; }
+
+    public PayfastPaymentConfirmationReceivedEvent() { }
+
+    private PayfastPaymentConfirmationReceivedEvent(PayfastWebhookPayload? payload, string paymentId)
+    {
+        Payload = payload;
+        CorrelationId = paymentId;
+    }
+
+    public static PayfastPaymentConfirmationReceivedEvent Create(PayfastWebhookPayload? payload, string paymentId) =>
+        new(payload, paymentId);
+}

LiteCharms.Features.MidrandBooks/Payments/PaymentService.cs

@@ -7,6 +7,27 @@ namespace LiteCharms.Features.MidrandBooks.Payments;
 
 public sealed class PaymentService(IDbContextFactory<MidrandBooksDbContext> contextFactory) : IService
 {
+    public async ValueTask<Result<Payment>> GetOrderPaymentAsync(long orderId, CancellationToken cancellationToken = default)
+    {
+        try
+        {
+            await using var context = await contextFactory.CreateDbContextAsync(cancellationToken);
+
+            var payment = await context.Payments.AsNoTracking()
+                .Where(p => p.OrderId == orderId)
+                .OrderByDescending(p => p.Id)
+                .FirstOrDefaultAsync(cancellationToken);
+
+            return payment is not null
+                ? Result.Ok(payment.ToModel())
+                : Result.Fail<Payment>("Could not find payment for the order");
+        }
+        catch (Exception ex)
+        {
+            return Result.Fail<Payment>(new Error(ex.Message).CausedBy(ex));
+        }
+    }
+
     public async ValueTask<Result<Refund>> GetRefundAsync(long refundId, CancellationToken cancellationToken = default)
     {
         try
@@ -95,6 +116,25 @@ public sealed class PaymentService(IDbContextFactory<MidrandBooksDbContext> cont
         }
     }
 
+    public async ValueTask<Result<bool>> HasLedgerEntryAsync(long orderId, long paymentId, long gatewayId, CancellationToken cancellationToken = default)
+    {
+        try
+        {
+            await using var context = await contextFactory.CreateDbContextAsync(cancellationToken);
+
+            var exists = await context.Ledger.AnyAsync(l =>
+                l.OrderId == orderId &&
+                l.PaymentId == paymentId &&
+                l.PaymentGatewayId == gatewayId, cancellationToken);
+
+            return Result.Ok(exists);
+        }
+        catch (Exception ex)
+        {
+            return Result.Fail(new Error(ex.Message).CausedBy(ex));
+        }
+    }
+
     public async ValueTask<Result> WriteLedgerEntryAsync(CreateLedgerEntry request, CancellationToken cancellationToken = default)
     {
         try

LiteCharms.Features.Tests/HashServiceFeatureTests.cs

@@ -1,4 +1,6 @@
 using LiteCharms.Features.Hasher;
+using LiteCharms.Features.Models;
+using static LiteCharms.Features.Extensions.Hash;
 
 namespace LiteCharms.Features.Tests;
 
@@ -65,17 +67,18 @@ public class HashServiceFeatureTests(Fixture fixture) : IClassFixture<Fixture>
     {
         var paymentId = hashService.HashEncodeLongId(1001).Value;
 
-        var incomingForm = new Dictionary<string, string>
+        var payload = new PayfastWebhookPayload
         {
-            { "m_payment_id", paymentId },
+            Amount = "350.00",
-            { "amount", "350.00" },
+            ItemName = "System Architecture Book",
-            { "item_name", "System Architecture Book" }
+            MPaymentId = paymentId,            
         };
 
-        var rawPayload = $"amount=350.00&item_name=System+Architecture+Book&m_payment_id={paymentId}&passphrase={payfastPassphrase}";
+        var rawPayload = payload.ToRawPayfastPayload(payfastPassphrase);
+
         var generatedSignature = HashService.ToMd5Hash(rawPayload).Value;
 
-        var result = hashService.VerifyPayfastWebhookSignature(incomingForm, generatedSignature);
+        var result = hashService.VerifyPayfastWebhookSignature(payload, generatedSignature);
 
         Assert.True(result.IsSuccess);
         Assert.True(result.Value);

LiteCharms.Features/Extensions/Hash.cs

@@ -1,5 +1,6 @@
 using LiteCharms.Features.Hasher;
 using LiteCharms.Features.Hasher.Configuration;
+using LiteCharms.Features.Models;
 
 namespace LiteCharms.Features.Extensions;
 
@@ -20,4 +21,82 @@ public static class Hash
 
         return services;
     }
+
+    public static string ToRawPayfastPayload(this PayfastWebhookPayload input, string passphrase)
+    {
+        var parameters = new List<string>();
+
+        if (!string.IsNullOrWhiteSpace(input.Amount))
+            parameters.Add($"amount={WebUtility.UrlEncode(input.Amount)}");
+
+        if (!string.IsNullOrWhiteSpace(input.ItemName))
+            parameters.Add($"item_name={WebUtility.UrlEncode(input.ItemName)}");
+
+        if (!string.IsNullOrWhiteSpace(input.MPaymentId))
+            parameters.Add($"m_payment_id={WebUtility.UrlEncode(input.MPaymentId)}");
+
+        string payload = string.Join("&", parameters);
+
+        if (!string.IsNullOrWhiteSpace(passphrase))
+            payload += $"&passphrase={WebUtility.UrlEncode(passphrase)}";
+
+        return payload;
+    }
+
+    public static (PayfastWebhookPayload Payload, string Passphrase) FromRawPayfastPayload(this string rawPayload)
+    {
+        string passphrase = string.Empty;
+        var payload = new PayfastWebhookPayload();
+
+        if (string.IsNullOrWhiteSpace(rawPayload)) return (payload, passphrase);
+
+        var segments = rawPayload.Split('&', StringSplitOptions.RemoveEmptyEntries);
+
+        foreach (var segment in segments)
+        {
+            int delimiterIndex = segment.IndexOf('=');
+            if (delimiterIndex == -1)
+                continue;
+
+            string key = segment[..delimiterIndex].Trim();
+            string rawValue = segment[(delimiterIndex + 1)..];
+
+            string decodedValue = WebUtility.UrlDecode(rawValue);
+
+            switch (key.ToLowerInvariant())
+            {
+                case "amount":
+                    payload.Amount = decodedValue;
+                    break;
+                case "item_name":
+                    payload.ItemName = decodedValue;
+                    break;
+                case "m_payment_id":
+                    payload.MPaymentId = decodedValue;
+                    break;
+                case "passphrase":
+                    passphrase = decodedValue;
+                    break;
+            }
+        }
+
+        return (payload, passphrase);
+    }
+
+    public static (PayfastWebhookPayload Payload, string Passphrase) FromRawPayfastPayload(this IFormCollection form)
+    {
+        string passphrase = string.Empty;
+        var payload = new PayfastWebhookPayload();
+
+        if (form.IsNullOrEmpty()) return (payload, passphrase);
+
+        payload = new PayfastWebhookPayload
+        {
+            Amount = form.TryGetValue("amount", out var amountValues) ? amountValues.ToString() : null,
+            ItemName = form.TryGetValue("item_name", out var itemValues) ? itemValues.ToString() : null,
+            MPaymentId = form.TryGetValue("m_payment_id", out var paymentIdValues) ? paymentIdValues.ToString() : null,
+        };
+
+        return (payload, passphrase);
+    }
 }

LiteCharms.Features/Hasher/HashService.cs

@@ -1,5 +1,6 @@
 using LiteCharms.Features.Abstractions;
 using LiteCharms.Features.Hasher.Configuration;
+using LiteCharms.Features.Models;
 
 namespace LiteCharms.Features.Hasher;
 
@@ -40,24 +41,30 @@ public sealed partial class HashService(IHashids hasher, IOptions<HasherSettings
         return Result.Ok(Convert.ToHexString(bytes).ToLowerInvariant());
     }
 
-    public Result<bool> VerifyPayfastWebhookSignature(IDictionary<string, string> incomingFormData, string incomingSignature)
+    public Result<bool> VerifyPayfastWebhookSignature(PayfastWebhookPayload payload, string incomingSignature)
     {
         try
         {
             if (string.IsNullOrWhiteSpace(incomingSignature))
                 return Result.Fail<bool>("Validation failed: Missing signature string parameter.");
 
-            var sortedFields = incomingFormData
+            var parameters = new List<string>();
-                .Where(field => !string.Equals(field.Key, "signature", StringComparison.OrdinalIgnoreCase))
-                .OrderBy(field => field.Key, StringComparer.Ordinal)
-                .Select(field => $"{field.Key}={WebUtility.UrlEncode(field.Value)}");
 
-            string payload = string.Join("&", sortedFields);
+            if (!string.IsNullOrWhiteSpace(payload.Amount))
+                parameters.Add($"amount={WebUtility.UrlEncode(payload.Amount)}");
+
+            if (!string.IsNullOrWhiteSpace(payload.ItemName))
+                parameters.Add($"item_name={WebUtility.UrlEncode(payload.ItemName)}");
+
+            if (!string.IsNullOrWhiteSpace(payload.MPaymentId))
+                parameters.Add($"m_payment_id={WebUtility.UrlEncode(payload.MPaymentId)}");
+
+            string signatureString = string.Join("&", parameters);
 
             if (!string.IsNullOrWhiteSpace(settings.PayfastPassphrase))
-                payload += $"&passphrase={WebUtility.UrlEncode(settings.PayfastPassphrase)}";
+                signatureString += $"&passphrase={WebUtility.UrlEncode(settings.PayfastPassphrase)}";
 
-            var localHashResult = ToMd5Hash(payload);
+            var localHashResult = ToMd5Hash(signatureString);
 
             if (!localHashResult.IsSuccess)
                 return Result.Fail<bool>(localHashResult.Errors);
@@ -68,7 +75,7 @@ public sealed partial class HashService(IHashids hasher, IOptions<HasherSettings
         }
         catch (Exception ex)
         {
-            return Result.Fail<bool>(new Error("An error occurred during MD5 verification loop.").CausedBy(ex));
+            return Result.Fail<bool>(new Error("An error occurred during Payfast MD5 verification.").CausedBy(ex));
         }
     }
 

LiteCharms.Features/LiteCharms.Features.csproj

@@ -147,6 +147,8 @@
 
   <!-- Shared Usings -->
   <ItemGroup>
+    <Using Include="Microsoft.IdentityModel.Tokens" />
+    <Using Include="Microsoft.AspNetCore.Http" />
     <Using Include="HashidsNet" />
     <Using Include="System.Net" />
     <Using Include="System.Text.RegularExpressions" />

LiteCharms.Features/Models/PayfastWebhookPayload.cs

@@ -0,0 +1,8 @@
+namespace LiteCharms.Features.Models;
+
+public sealed class PayfastWebhookPayload
+{
+    public string? Amount { get; set; }
+    public string? ItemName { get; set; }
+    public string? MPaymentId { get; set; }
+}

LiteCharms.Features/Quartz/JobOrchestrator.cs

@@ -23,7 +23,7 @@ public sealed class JobOrchestrator(ISchedulerFactory schedulerFactory) : IJobOr
 
         var trigger = global::Quartz.TriggerBuilder.Create()
             .WithIdentity(triggerKey)
-            .StartNow()
+            .StartNow()            
             .Build();
 
         await scheduler.ScheduleJob(job, new List<ITrigger> { trigger }.AsReadOnly(), replace: true, cancellationToken);