Merge pull request 'payments' (#60) from payments into master

Reviewed-on: #60

LiteCharms.Features.MidrandBooks.Seed/LiteCharms.Features.MidrandBooks.Seed.csproj

@@ -116,8 +116,8 @@
 
   <!-- Amazon S3 SDK -->
   <ItemGroup>
-    <PackageReference Include="AWSSDK.Extensions.NetCore.Setup" Version="4.0.4.1" />
+    <PackageReference Include="AWSSDK.Extensions.NetCore.Setup" Version="4.0.4.3" />
-    <PackageReference Include="AWSSDK.S3" Version="4.0.23.4" />
+    <PackageReference Include="AWSSDK.S3" Version="4.0.24" />
     <ProjectReference Include="..\LiteCharms.Features\LiteCharms.Features.csproj" />
 
     <!-- global Usings -->

LiteCharms.Features.MidrandBooks.Tests/Common/Fixture.cs

@@ -25,6 +25,7 @@ public class Fixture : IDisposable
             .Build();
 
         Services = new ServiceCollection()
+            .AddHttpClient()
             .AddMediator()
             .AddLogging()
             .AddEmailServiceBus()
@@ -33,6 +34,7 @@ public class Fixture : IDisposable
             .AddEmailServices(Configuration)
             .AddSingleton(Configuration)
             .AddShopServices()
+            .AddHashServices(Configuration)
             .BuildServiceProvider();
 
         Mediator = Services.GetRequiredService<IMediator>();

LiteCharms.Features.MidrandBooks.Tests/LiteCharms.Features.MidrandBooks.Tests.csproj

@@ -17,7 +17,7 @@
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
-    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.5.1" />
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.6.0" />
     <PackageReference Include="xunit" Version="2.9.3" />
     <PackageReference Include="xunit.runner.visualstudio" Version="3.1.5">
       <PrivateAssets>all</PrivateAssets>
@@ -39,6 +39,7 @@
   </ItemGroup>
 
   <ItemGroup>
+    <Using Include="System.Net" />
     <Using Include="System.Text.Json" />
     <Using Include="System.Diagnostics" />
     <Using Include="Xunit" />

LiteCharms.Features.MidrandBooks.Tests/PayfastServiceFeatureTests.cs

@@ -0,0 +1,113 @@
+using LiteCharms.Features.MidrandBooks.Payments;
+using LiteCharms.Features.MidrandBooks.Payments.Models;
+using LiteCharms.Features.MidrandBooks.Tests.Common;
+
+namespace LiteCharms.Features.MidrandBooks.Tests;
+
+public sealed class PayfastServiceFeatureTests(Fixture fixture) : IClassFixture<Fixture>
+{
+    private readonly PayfastService payfastService = fixture.Services.GetRequiredService<PayfastService>();
+
+    [IntegrationFact]
+    public async Task WriteLedgerEntryAsync_ShouldReturn_ResultWithGatewayLedgerId()
+    {
+        var request = new CreateGatewayLedgerEntry
+        {
+            OrderId = 1,
+            PaymentId = 1,
+            MerchantPaymentId = "M_REF_TEST_99",
+            PayfastPaymentId = "PF_SYS_ID_10023",
+            CustomerEmail = "buyer@litecharms.co.za",
+            AmountGross = 350.00m,
+            AmountFee = 12.50m,
+            AmountNet = 337.50m,
+            PaymentStatus = "COMPLETE"
+        };
+
+        var result = await payfastService.WriteLedgerEntryAsync(request, fixture.CancellationToken);
+
+        Assert.True(result.IsSuccess);
+        Assert.True(result.Value > 0);
+    }
+
+    [IntegrationFact]
+    public async Task ValidateReferrerIpAsync_WithValidPayfastHostIp_ShouldReturnTrue()
+    {
+        var addresses = await Dns.GetHostAddressesAsync("sandbox.payfast.co.za", fixture.CancellationToken);
+
+        string liveTargetIp = addresses.First().ToString();
+
+        var result = await payfastService.ValidateReferrerIpAsync(liveTargetIp, fixture.CancellationToken);
+
+        Assert.True(result.IsSuccess);
+        Assert.True(result.Value);
+    }
+
+    [IntegrationFact]
+    public async Task ValidateReferrerIpAsync_WithUntrustedIp_ShouldReturnFalse()
+    {
+        string rogueIp = "8.8.8.8";
+
+        var result = await payfastService.ValidateReferrerIpAsync(rogueIp, fixture.CancellationToken);
+
+        Assert.True(result.IsSuccess);
+        Assert.False(result.Value);
+    }
+
+    [IntegrationFact]
+    public void ValidatePaymentAmount_WhenWithinAllowableDelta_ShouldReturnTrue()
+    {
+        decimal systemExpectedTotal = 199.99m;
+        string gatewayClearedGross = "200.00"; // Variance is exactly R0.01
+
+        var result = payfastService.ValidatePaymentAmount(systemExpectedTotal, gatewayClearedGross);
+
+        Assert.True(result.IsSuccess);
+        Assert.True(result.Value);
+    }
+
+    [IntegrationFact]
+    public void ValidatePaymentAmount_WhenVarianceBreachesDeltaBounds_ShouldReturnFalse()
+    {
+        decimal systemExpectedTotal = 199.99m;
+        string gatewayClearedGross = "150.00";
+
+        var result = payfastService.ValidatePaymentAmount(systemExpectedTotal, gatewayClearedGross);
+
+        Assert.True(result.IsSuccess);
+        Assert.False(result.Value);
+    }
+
+    [IntegrationFact]
+    public async Task ValidateServerConfirmationAsync_WithUnrecognizedPayload_ShouldReturnFalseFromCentralGateway()
+    {
+        // Arrange - Execute against actual Payfast servers using raw mock parameters. 
+        // The server handshake will return 200 OK with string payload 'INVALID'
+        string arbitraryParameters = "merchant_id=10000000&payment_status=COMPLETE";
+
+        var result = await payfastService.ValidateServerConfirmationAsync(arbitraryParameters, isSandbox: true, fixture.CancellationToken);
+
+        Assert.True(result.IsSuccess); 
+        Assert.False(result.Value);   // Handshake data rejected as fraudulent/unrecognized
+    }
+
+    [IntegrationFact]
+    public void GenerateSignature_WithStandardTelemetryData_ShouldSucceedAndHashString()
+    {
+        var telemetryPayload = new Dictionary<string, string?>
+        {
+            { "merchant_id", "10049307" },
+            { "merchant_key", "ju6navn0jcbf0" },
+            { "amount_gross", "250.00" },
+            { "item_name", "Midrand School Textbook Variant A" }
+        };
+
+        string passphrase = "oauth_test_signature_pass";
+
+        var result = PayfastService.GenerateSignature(telemetryPayload, passphrase);
+
+        Assert.True(result.IsSuccess);
+        Assert.False(string.IsNullOrWhiteSpace(result.Value));
+        Assert.Equal(32, result.Value.Length); // MD5 outputs hex representations totaling 32 characters
+    }
+}

LiteCharms.Features.MidrandBooks.Tests/appsettings.json

@@ -1,4 +1,16 @@
 {
+  "ValidPayfastHosts": [
+    "www.payfast.co.za",
+    "sandbox.payfast.co.za",
+    "w1w.payfast.co.za",
+    "w2w.payfast.co.za",
+    "ips.payfast.co.za",
+    "api.payfast.co.za",
+    "payment.payfast.io"
+  ],
+  "HasherSettings": {
+    "MinHashLength": 11
+  },
   "BookshopS3Settings": {
     "ServiceUrl": "http://192.168.1.177:30900",
     "Region": "garage",

LiteCharms.Features.MidrandBooks/Extensions/Mappers.cs

@@ -6,12 +6,26 @@ using LiteCharms.Features.MidrandBooks.Orders.Models;
 using LiteCharms.Features.MidrandBooks.Pages.Models;
 using LiteCharms.Features.MidrandBooks.Payments.Models;
 using LiteCharms.Features.MidrandBooks.Products.Models;
-using Microsoft.CodeAnalysis.CSharp.Syntax;
 
 namespace LiteCharms.Features.MidrandBooks.Extensions;
 
 public static class Mappers
 {
+    public static PaymentGatewayLedger ToModel(this Payments.Entities.PaymentGatewayLedger entity) => new()
+    {
+        Id = entity.Id,
+        CreatedAt = entity.CreatedAt,
+        CustomerEmail = entity.CustomerEmail,
+        OrderId = entity.OrderId,
+        PaymentId = entity.PaymentId,
+        MerchantPaymentId = entity.MerchantPaymentId,
+        PayfastPaymentId = entity.PayfastPaymentId,
+        PaymentStatus = entity.PaymentStatus,
+        AmountGross = entity.AmountGross,
+        AmountFee = entity.AmountFee,
+        AmountNet = entity.AmountNet        
+    };
+
     public static Refund ToModel(this Payments.Entities.Refund entity) => new()
     {
         CreatedAt = entity.CreatedAt,
@@ -30,10 +44,9 @@ public static class Mappers
         CreatedAt = entity.CreatedAt,
         CustomerId = entity.CustomerId,
         OrderId = entity.OrderId,
-        PaymentGatewayId = entity.PaymentGatewayId,
-        PaymentGatewayReference = entity.PaymentGatewayReference,
         PaymentId = entity.PaymentId,
         Status = entity.Status,
+        MerchantPaymentId = entity.MerchantPaymentId,
     };
 
     public static PaymentGateway ToModel(this Payments.Entities.PaymentGateway entity) => new()

LiteCharms.Features.MidrandBooks/LiteCharms.Features.MidrandBooks.csproj

@@ -136,8 +136,8 @@
 
   <!-- Amazon S3 SDK -->
   <ItemGroup>
-    <PackageReference Include="AWSSDK.Extensions.NetCore.Setup" Version="4.0.4.1" />
+    <PackageReference Include="AWSSDK.Extensions.NetCore.Setup" Version="4.0.4.3" />
-    <PackageReference Include="AWSSDK.S3" Version="4.0.23.4" />
+    <PackageReference Include="AWSSDK.S3" Version="4.0.24" />
     <ProjectReference Include="..\LiteCharms.Features\LiteCharms.Features.csproj" />
 
     <!-- global Usings -->
@@ -148,6 +148,10 @@
 
   <!-- Shared Usings -->
   <ItemGroup>
+    <Using Include="System.Net.Sockets" />
+    <Using Include="System.Text.RegularExpressions" />
+    <Using Include="System.Web" />
+    <Using Include="System.Net" />
     <Using Include="Humanizer" />
     <Using Include="System.Globalization" />
     <Using Include="System.Reflection" />

LiteCharms.Features.MidrandBooks/Payments/Entities/PaymentGatewayLedger.cs

@@ -0,0 +1,11 @@
+using LiteCharms.Features.MidrandBooks.Orders.Entities;
+
+namespace LiteCharms.Features.MidrandBooks.Payments.Entities;
+
+[EntityTypeConfiguration<PaymentGatewayLedgerConfiguration, PaymentGatewayLedger>]
+public class PaymentGatewayLedger : Models.PaymentGatewayLedger
+{
+    public virtual Order? Order { get; set; }
+
+    public virtual Payment? Payment { get; set; }
+}

LiteCharms.Features.MidrandBooks/Payments/Entities/PaymentGatewayLedgerConfiguration.cs

@@ -0,0 +1,30 @@
+namespace LiteCharms.Features.MidrandBooks.Payments.Entities;
+
+public sealed class PaymentGatewayLedgerConfiguration : IEntityTypeConfiguration<PaymentGatewayLedger>
+{
+    public void Configure(EntityTypeBuilder<PaymentGatewayLedger> builder)
+    {
+        builder.ToTable("GatewayLedger");
+
+        builder.HasKey(f  => f.Id);
+        builder.Property(f => f.CreatedAt).IsRequired().ValueGeneratedOnAdd().HasDefaultValueSql("now()");
+        builder.Property(f => f.OrderId).IsRequired();
+        builder.Property(f => f.PaymentId).IsRequired();
+        builder.Property(f => f.PayfastPaymentId).IsRequired();
+        builder.Property(f => f.MerchantPaymentId).IsRequired();
+        builder.Property(f => f.AmountGross).IsRequired().HasPrecision(18, 2);        
+        builder.Property(f => f.AmountFee).IsRequired().HasPrecision(18, 2);        
+        builder.Property(f => f.AmountNet).IsRequired().HasPrecision(18, 2);        
+        builder.Property(f => f.CustomerEmail).IsRequired(false);
+
+        builder.HasOne(f => f.Order)
+            .WithMany()
+            .HasForeignKey(f => f.OrderId)
+            .OnDelete(DeleteBehavior.Cascade);
+
+        builder.HasOne(f => f.Payment)
+            .WithMany()
+            .HasForeignKey(f => f.PaymentId)
+            .OnDelete(DeleteBehavior.Cascade);
+    }
+}

LiteCharms.Features.MidrandBooks/Payments/Entities/PaymentLedger.cs

@@ -11,6 +11,4 @@ public class PaymentLedger : Models.PaymentLedger
     public virtual Order? Order { get; set; }
 
     public virtual Customer? Customer { get; set; }
-
-    public virtual PaymentGateway? Gateway { get; set; }
 }

LiteCharms.Features.MidrandBooks/Payments/Entities/PaymentLedgerConfiguration.cs

@@ -9,8 +9,7 @@ public sealed class PaymentLedgerConfiguration : IEntityTypeConfiguration<Paymen
         builder.HasKey(f => f.Id);
         builder.Property(f => f.CreatedAt).IsRequired().ValueGeneratedOnAdd().HasDefaultValueSql("now()");
         builder.Property(f => f.Status).IsRequired();
-        builder.Property(f => f.PaymentGatewayReference).IsRequired(false);
+        builder.Property(f => f.MerchantPaymentId).IsRequired(false);
-        builder.Property(f => f.PaymentGatewayId).IsRequired(false);
         builder.Property(f => f.OrderId).IsRequired();
         builder.Property(f => f.CustomerId).IsRequired();
         builder.Property(f => f.PaymentId).IsRequired();
@@ -31,11 +30,5 @@ public sealed class PaymentLedgerConfiguration : IEntityTypeConfiguration<Paymen
             .WithMany()
             .IsRequired()
             .HasForeignKey(f => f.CustomerId);
-
-        builder.HasOne(f => f.Gateway)
-            .WithMany()
-            .IsRequired(false)
-            .HasForeignKey(f => f.PaymentGatewayId)
-            .OnDelete(DeleteBehavior.Cascade);
     }
 }

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

@@ -0,0 +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, 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>();
+
+        var payload = notification.Payload ?? throw new Exception("Payload metadata context context is null.");
+
+        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.LogCritical("Incoming webhook signature verification failed. Possible payload tampering.");
+
+            return;
+        }
+
+        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
+        {
+            OrderId = orderResult.Value.Id,
+            PaymentId = paymentResult.Value.Id,
+            MerchantPaymentId = payload.MerchantPaymentId!,
+            PayfastPaymentId = payload.PaymentId,
+            CustomerEmail = payload.EmailAddress,
+            AmountFee = fee,
+            AmountGross = gross,
+            AmountNet = net,
+            PaymentStatus = status,            
+        }, cancellationToken);
+
+        if (status.Equals("COMPLETE", StringComparison.OrdinalIgnoreCase))
+        {
+            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);
+
+            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
+        {
+            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);
+        }
+    }
+}

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

@@ -0,0 +1,27 @@
+using LiteCharms.Features.Abstractions;
+using LiteCharms.Features.MidrandBooks.Payments.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 string? RemoteIpAddress { get; set; }
+
+    public bool PerformBackgroundChecks { get; set; }
+
+    public PayfastPaymentConfirmationReceivedEvent() { }
+
+    private PayfastPaymentConfirmationReceivedEvent(PayfastWebhookPayload? payload, string paymentId, bool performBackgroundChecks = true)
+    {
+        Payload = payload;
+        CorrelationId = paymentId;
+        PerformBackgroundChecks = performBackgroundChecks;
+    }
+
+    public static PayfastPaymentConfirmationReceivedEvent Create(PayfastWebhookPayload? payload, string paymentId, bool performBackgroundChecks = true) =>
+        new(payload, paymentId, performBackgroundChecks);
+}

LiteCharms.Features.MidrandBooks/Payments/Models/PayfastWebhookPayload.cs

@@ -0,0 +1,59 @@
+namespace LiteCharms.Features.MidrandBooks.Payments.Models;
+
+public sealed class PayfastWebhookPayload
+{
+    public string? MerchantId { get; set; }
+
+    public string? MerchantKey { get; set; }
+
+    public string? Signature { get; set; }
+
+    public string? MerchantPaymentId { get; set; }
+
+    public string? PaymentId { get; set; }
+
+    public string? PaymentStatus { get; set; }
+
+    public string? ItemName { get; set; }
+
+    public string? ItemDescription { get; set; }
+
+    public string? AmountGross { get; set; }
+
+    public string? AmountFee { get; set; }
+
+    public string? AmountNet { get; set; }
+
+    public string? NameFirst { get; set; }
+
+    public string? NameLast { get; set; }
+
+    public string? EmailAddress { get; set; }
+
+    public string? CustomStr1 { get; set; }
+
+    public string? CustomInt1 { get; set; }
+
+    public string? Token { get; set; }
+
+    public IDictionary<string, string?> ToParamDictionary() => new Dictionary<string, string?>
+        (StringComparer.Ordinal)
+        {
+            { "merchant_id", MerchantId },
+            { "merchant_key", MerchantKey },
+            { "m_payment_id", MerchantPaymentId },
+            { "pf_payment_id", PaymentId },
+            { "payment_status", PaymentStatus },
+            { "item_name", ItemName },
+            { "item_description", ItemDescription },
+            { "amount_gross", AmountGross },
+            { "amount_fee", AmountFee },
+            { "amount_net", AmountNet },
+            { "custom_str1", CustomStr1 },
+            { "custom_int1", CustomInt1 },
+            { "name_first", NameFirst },
+            { "name_last", NameLast },
+            { "email_address", EmailAddress },
+            { "token", Token }
+        };
+}

LiteCharms.Features.MidrandBooks/Payments/Models/PaymentGatewayLedger.cs

@@ -0,0 +1,26 @@
+namespace LiteCharms.Features.MidrandBooks.Payments.Models;
+
+public class PaymentGatewayLedger
+{
+    public long Id { get; set; }
+
+    public DateTime CreatedAt { get; set; }
+
+    public string? CustomerEmail { get; set; }
+
+    public long OrderId { get; set; }
+
+    public long PaymentId { get; set; }
+
+    public string? MerchantPaymentId { get; set; }
+
+    public string? PayfastPaymentId { get; set; }
+
+    public string? PaymentStatus { get; set; }
+
+    public decimal AmountGross { get; set; }
+
+    public decimal AmountFee { get; set; }
+
+    public decimal AmountNet { get; set; }
+}

LiteCharms.Features.MidrandBooks/Payments/Models/PaymentLedger.cs

@@ -14,7 +14,5 @@ public class PaymentLedger
 
     public long CustomerId { get; set; }
 
-    public string? PaymentGatewayReference { get; set; }
+    public string? MerchantPaymentId { get; set; }
-
-    public long? PaymentGatewayId { get; set; }
 }

LiteCharms.Features.MidrandBooks/Payments/Models/Records.cs

@@ -1,5 +1,26 @@
 namespace LiteCharms.Features.MidrandBooks.Payments.Models;
 
+public sealed record CreateGatewayLedgerEntry
+{
+    public string? CustomerEmail { get; set; }
+
+    public required long OrderId { get; set; }
+
+    public required long PaymentId { get; set; }
+
+    public string? MerchantPaymentId { get; set; }
+
+    public string? PayfastPaymentId { get; set; }
+
+    public string? PaymentStatus { get; set; }
+
+    public decimal AmountGross { get; set; }
+
+    public decimal AmountFee { get; set; }
+
+    public decimal AmountNet { get; set; }
+}
+
 public sealed record UpdateRefund
 {
     public long OrderId { get; set; }

LiteCharms.Features.MidrandBooks/Payments/PayfastService.cs

@@ -0,0 +1,171 @@
+using LiteCharms.Features.Abstractions;
+using LiteCharms.Features.Hasher;
+using LiteCharms.Features.MidrandBooks.Payments.Models;
+using LiteCharms.Features.MidrandBooks.Postgres;
+
+namespace LiteCharms.Features.MidrandBooks.Payments;
+
+public sealed partial class PayfastService(IDbContextFactory<MidrandBooksDbContext> contextFactory, 
+    ILogger<PayfastService> logger, IHttpClientFactory httpClientFactory, IConfiguration configuration) : IService
+{
+    [GeneratedRegex(@"%[0-9A-Fa-f]{2}", RegexOptions.None, matchTimeoutMilliseconds: 1000)]
+    public static partial Regex PercentEncodingRegex { get; }
+
+    public readonly string[] ValidHosts = configuration.GetSection("ValidPayfastHosts").Get<string[]>() ?? [];
+
+    public async ValueTask<Result<long>> WriteLedgerEntryAsync(CreateGatewayLedgerEntry request, CancellationToken cancellationToken = default)
+    {
+        try
+        {
+            await using var context = await contextFactory.CreateDbContextAsync(cancellationToken);
+
+            if(!await context.Orders.AnyAsync(o => o.Id == request.OrderId, cancellationToken))
+                return Result.Fail<long>("Referenced order ID does not exist in database.");
+
+            if(!await context.Payments.AnyAsync(p => p.Id == request.PaymentId, cancellationToken))
+                return Result.Fail<long>("Referenced payment ID does not exist in database.");
+
+            var entry = context.GatewayLedger.Add(new Entities.PaymentGatewayLedger
+            {
+                CustomerEmail = request.CustomerEmail,
+                OrderId = request.OrderId,
+                PaymentId = request.PaymentId,
+                MerchantPaymentId = request.MerchantPaymentId,
+                PayfastPaymentId = request.PayfastPaymentId,
+                PaymentStatus = request.PaymentStatus,
+                AmountGross = request.AmountGross,
+                AmountFee = request.AmountFee,
+                AmountNet = request.AmountNet,
+                CreatedAt = DateTime.UtcNow,                
+            });
+
+            return await context.SaveChangesAsync(cancellationToken) > 0
+                ? Result.Ok(entry.Entity.Id)
+                : Result.Fail<long>("Failed to save Payfast ledger entry to database.");
+        }
+        catch (Exception ex)
+        {
+            return Result.Fail<long>(new Error("Failed to write Payfast ledger entry to database.").CausedBy(ex));
+        }
+    }
+
+    public async ValueTask<Result<bool>> ValidateReferrerIpAsync(string remoteIpAddress, CancellationToken cancellationToken = default)
+    {
+        if (string.IsNullOrWhiteSpace(remoteIpAddress)) 
+            return Result.Fail<bool>("Remote IP address is null or whitespace.");
+
+        try
+        {
+            var validIps = new HashSet<IPAddress>();
+
+            foreach (var host in ValidHosts)
+            {
+                try
+                {
+                    var addresses = await Dns.GetHostAddressesAsync(host, cancellationToken);
+
+                    foreach (var addr in addresses) validIps.Add(addr);
+                }
+                catch (SocketException ex)
+                {
+                    logger.LogWarning(ex, "DNS warning: Failed to resolve Payfast node '{Host}'. It may be decommissioned or unreachable.", host);
+                }
+            }
+
+            if (IPAddress.TryParse(remoteIpAddress, out var incomingIp))
+            {
+                bool isValid = validIps.Contains(incomingIp);
+
+                if (!isValid)
+                    logger.LogWarning("SECURITY ALERT: Webhook IP '{RemoteIp}' originated from an unlisted host schema.", remoteIpAddress);
+
+                return Result.Ok(isValid);
+            }
+
+            return Result.Fail<bool>("Invalid remote IP address format.");
+        }
+        catch (Exception ex)
+        {
+            return Result.Fail<bool>(new Error("DNS Verification error while scanning Payfast IP nodes.").CausedBy(ex));
+        }
+    }
+
+    public Result<bool> ValidatePaymentAmount(decimal expectedTotal, string? amountGrossString)
+    {
+        if (!decimal.TryParse(amountGrossString, CultureInfo.InvariantCulture, out decimal grossAmount))
+            return Result.Fail<bool>("Failed to parse payment amount.");
+
+        decimal delta = Math.Abs(expectedTotal - grossAmount);
+
+        bool isAmountValid = delta <= 0.01m;
+
+        if (!isAmountValid)
+            logger.LogError("FINANCIAL DRIFT EXCEPTION: Expected order total R{Expected} but gateway cleared R{Cleared}.", expectedTotal, grossAmount);
+
+        return Result.Ok(isAmountValid);
+    }
+
+    public async ValueTask<Result<bool>> ValidateServerConfirmationAsync(string rawQueryParamString, bool isSandbox, CancellationToken ct)
+    {
+        try
+        {
+            string host = isSandbox ? "sandbox.payfast.co.za" : "www.payfast.co.za";
+            string targetUrl = $"https://{host}/eng/query/validate";
+
+            using var content = new StringContent(rawQueryParamString, Encoding.UTF8, "application/x-www-form-urlencoded");
+
+            var httpClient = httpClientFactory.CreateClient();
+
+            var response = await httpClient.PostAsync(targetUrl, content, ct);
+
+            if (!response.IsSuccessStatusCode) return Result.Fail<bool>("Failed to validate server confirmation.");
+
+            string responseText = await response.Content.ReadAsStringAsync(ct);
+
+            bool isValidated = string.Equals(responseText.Trim(), "VALID", StringComparison.OrdinalIgnoreCase);
+
+            if (!isValidated)
+                logger.LogWarning("SECURITY WARNING: Payfast back-channel returned validation response: '{Response}'", responseText);
+
+            return Result.Ok(isValidated);
+        }
+        catch (Exception ex)
+        {
+            return Result.Fail<bool>(new Error("Failed to complete back-channel cURL verification handshakes with Payfast remote endpoints.").CausedBy(ex));
+        }
+    }
+
+    public static Result<string> GenerateSignature(IDictionary<string, string?> data, string? passPhrase = null)
+    {
+        var pfOutput = new StringBuilder();
+
+        foreach (var kvp in data)
+        {
+            if (string.IsNullOrEmpty(kvp.Value))
+                continue;
+
+            string key = kvp.Key;
+
+            string encodedVal = HttpUtility.UrlEncode(kvp.Value.Trim());
+
+            string val = PercentEncodingRegex.Replace(encodedVal, m => m.Value.ToLowerInvariant());
+
+            pfOutput.Append($"{key}={val}&");
+        }
+
+        string getString = pfOutput.Length > 0
+            ? pfOutput.ToString()[..^1]
+            : string.Empty;
+
+        if (!string.IsNullOrWhiteSpace(passPhrase))
+        {
+            string encodedPassphrase = HttpUtility.UrlEncode(passPhrase.Trim());
+
+            string safePassphrase = PercentEncodingRegex.Replace(encodedPassphrase, m => m.Value.ToLowerInvariant());
+
+            getString += $"&passphrase={safePassphrase}";
+        }
+
+        return HashService.ToMd5Hash(getString);
+    }    
+}

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,24 @@ public sealed class PaymentService(IDbContextFactory<MidrandBooksDbContext> cont
         }
     }
 
+    public async ValueTask<Result<bool>> HasLedgerEntryAsync(long orderId, long paymentId, 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, 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
@@ -122,8 +161,6 @@ public sealed class PaymentService(IDbContextFactory<MidrandBooksDbContext> cont
                 CreatedAt = DateTime.UtcNow,
                 CustomerId = request.CustomerId,
                 OrderId = request.OrderId,
-                PaymentGatewayId = request.PaymentGatewayId,
-                PaymentGatewayReference = request.PaymentGatewayReference,
                 PaymentId = request.PaymentId,
                 Status = request.Status,
             });

LiteCharms.Features.MidrandBooks/Postgres/MidrandBooksDbContext.cs

@@ -48,4 +48,6 @@ public sealed class MidrandBooksDbContext(DbContextOptions<MidrandBooksDbContext
     public DbSet<PaymentGateway> Gateways => Set<PaymentGateway>();
 
     public DbSet<PaymentLedger> Ledger => Set<PaymentLedger>();
+
+    public DbSet<PaymentGatewayLedger> GatewayLedger => Set<PaymentGatewayLedger>();
 }

LiteCharms.Features.MidrandBooks/Postgres/Migrations/20260602202421_AddedPaymentGatewayLedger.cs

@@ -0,0 +1,108 @@
+using System;
+using Microsoft.EntityFrameworkCore.Migrations;
+using Npgsql.EntityFrameworkCore.PostgreSQL.Metadata;
+
+#nullable disable
+
+namespace LiteCharms.Features.MidrandBooks.Postgres.Migrations
+{
+    /// <inheritdoc />
+    public partial class AddedPaymentGatewayLedger : Migration
+    {
+        /// <inheritdoc />
+        protected override void Up(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.DropForeignKey(
+                name: "FK_Ledger_Gateways_PaymentGatewayId",
+                table: "Ledger");
+
+            migrationBuilder.DropIndex(
+                name: "IX_Ledger_PaymentGatewayId",
+                table: "Ledger");
+
+            migrationBuilder.DropColumn(
+                name: "PaymentGatewayId",
+                table: "Ledger");
+
+            migrationBuilder.RenameColumn(
+                name: "PaymentGatewayReference",
+                table: "Ledger",
+                newName: "MerchantPaymentId");
+
+            migrationBuilder.CreateTable(
+                name: "GatewayLedger",
+                columns: table => new
+                {
+                    Id = table.Column<long>(type: "bigint", nullable: false)
+                        .Annotation("Npgsql:ValueGenerationStrategy", NpgsqlValueGenerationStrategy.IdentityByDefaultColumn),
+                    CreatedAt = table.Column<DateTime>(type: "timestamp with time zone", nullable: false, defaultValueSql: "now()"),
+                    CustomerEmail = table.Column<string>(type: "text", nullable: true),
+                    OrderId = table.Column<long>(type: "bigint", nullable: false),
+                    PaymentId = table.Column<long>(type: "bigint", nullable: false),
+                    MerchantPaymentId = table.Column<string>(type: "text", nullable: true),
+                    PayfastPaymentId = table.Column<string>(type: "text", nullable: false),
+                    PaymentStatus = table.Column<string>(type: "text", nullable: true),
+                    AmountGross = table.Column<decimal>(type: "numeric(18,2)", precision: 18, scale: 2, nullable: false),
+                    AmountFee = table.Column<decimal>(type: "numeric(18,2)", precision: 18, scale: 2, nullable: false),
+                    AmountNet = table.Column<decimal>(type: "numeric(18,2)", precision: 18, scale: 2, nullable: false)
+                },
+                constraints: table =>
+                {
+                    table.PrimaryKey("PK_GatewayLedger", x => x.Id);
+                    table.ForeignKey(
+                        name: "FK_GatewayLedger_Orders_OrderId",
+                        column: x => x.OrderId,
+                        principalTable: "Orders",
+                        principalColumn: "Id",
+                        onDelete: ReferentialAction.Cascade);
+                    table.ForeignKey(
+                        name: "FK_GatewayLedger_Payments_PaymentId",
+                        column: x => x.PaymentId,
+                        principalTable: "Payments",
+                        principalColumn: "Id",
+                        onDelete: ReferentialAction.Cascade);
+                });
+
+            migrationBuilder.CreateIndex(
+                name: "IX_GatewayLedger_OrderId",
+                table: "GatewayLedger",
+                column: "OrderId");
+
+            migrationBuilder.CreateIndex(
+                name: "IX_GatewayLedger_PaymentId",
+                table: "GatewayLedger",
+                column: "PaymentId");
+        }
+
+        /// <inheritdoc />
+        protected override void Down(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.DropTable(
+                name: "GatewayLedger");
+
+            migrationBuilder.RenameColumn(
+                name: "MerchantPaymentId",
+                table: "Ledger",
+                newName: "PaymentGatewayReference");
+
+            migrationBuilder.AddColumn<long>(
+                name: "PaymentGatewayId",
+                table: "Ledger",
+                type: "bigint",
+                nullable: true);
+
+            migrationBuilder.CreateIndex(
+                name: "IX_Ledger_PaymentGatewayId",
+                table: "Ledger",
+                column: "PaymentGatewayId");
+
+            migrationBuilder.AddForeignKey(
+                name: "FK_Ledger_Gateways_PaymentGatewayId",
+                table: "Ledger",
+                column: "PaymentGatewayId",
+                principalTable: "Gateways",
+                principalColumn: "Id",
+                onDelete: ReferentialAction.Cascade);
+        }
+    }
+}

LiteCharms.Features.MidrandBooks/Postgres/Migrations/20260602205838_AddedPayfastPaymentIdToPaymentGatewayLedger.cs

@@ -0,0 +1,36 @@
+using Microsoft.EntityFrameworkCore.Migrations;
+
+#nullable disable
+
+namespace LiteCharms.Features.MidrandBooks.Postgres.Migrations
+{
+    /// <inheritdoc />
+    public partial class AddedPayfastPaymentIdToPaymentGatewayLedger : Migration
+    {
+        /// <inheritdoc />
+        protected override void Up(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.AlterColumn<string>(
+                name: "MerchantPaymentId",
+                table: "GatewayLedger",
+                type: "text",
+                nullable: false,
+                defaultValue: "",
+                oldClrType: typeof(string),
+                oldType: "text",
+                oldNullable: true);
+        }
+
+        /// <inheritdoc />
+        protected override void Down(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.AlterColumn<string>(
+                name: "MerchantPaymentId",
+                table: "GatewayLedger",
+                type: "text",
+                nullable: true,
+                oldClrType: typeof(string),
+                oldType: "text");
+        }
+    }
+}

LiteCharms.Features.MidrandBooks/Postgres/Migrations/MidrandBooksDbContextModelSnapshot.cs

@@ -615,6 +615,60 @@ namespace LiteCharms.Features.MidrandBooks.Postgres.Migrations
                     b.ToTable("Gateways", (string)null);
                 });
 
+            modelBuilder.Entity("LiteCharms.Features.MidrandBooks.Payments.Entities.PaymentGatewayLedger", b =>
+                {
+                    b.Property<long>("Id")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("bigint");
+
+                    NpgsqlPropertyBuilderExtensions.UseIdentityByDefaultColumn(b.Property<long>("Id"));
+
+                    b.Property<decimal>("AmountFee")
+                        .HasPrecision(18, 2)
+                        .HasColumnType("numeric(18,2)");
+
+                    b.Property<decimal>("AmountGross")
+                        .HasPrecision(18, 2)
+                        .HasColumnType("numeric(18,2)");
+
+                    b.Property<decimal>("AmountNet")
+                        .HasPrecision(18, 2)
+                        .HasColumnType("numeric(18,2)");
+
+                    b.Property<DateTime>("CreatedAt")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("timestamp with time zone")
+                        .HasDefaultValueSql("now()");
+
+                    b.Property<string>("CustomerEmail")
+                        .HasColumnType("text");
+
+                    b.Property<string>("MerchantPaymentId")
+                        .IsRequired()
+                        .HasColumnType("text");
+
+                    b.Property<long>("OrderId")
+                        .HasColumnType("bigint");
+
+                    b.Property<string>("PayfastPaymentId")
+                        .IsRequired()
+                        .HasColumnType("text");
+
+                    b.Property<long>("PaymentId")
+                        .HasColumnType("bigint");
+
+                    b.Property<string>("PaymentStatus")
+                        .HasColumnType("text");
+
+                    b.HasKey("Id");
+
+                    b.HasIndex("OrderId");
+
+                    b.HasIndex("PaymentId");
+
+                    b.ToTable("GatewayLedger", (string)null);
+                });
+
             modelBuilder.Entity("LiteCharms.Features.MidrandBooks.Payments.Entities.PaymentLedger", b =>
                 {
                     b.Property<long>("Id")
@@ -631,15 +685,12 @@ namespace LiteCharms.Features.MidrandBooks.Postgres.Migrations
                     b.Property<long>("CustomerId")
                         .HasColumnType("bigint");
 
+                    b.Property<string>("MerchantPaymentId")
+                        .HasColumnType("text");
+
                     b.Property<long>("OrderId")
                         .HasColumnType("bigint");
 
-                    b.Property<long?>("PaymentGatewayId")
-                        .HasColumnType("bigint");
-
-                    b.Property<string>("PaymentGatewayReference")
-                        .HasColumnType("text");
-
                     b.Property<long>("PaymentId")
                         .HasColumnType("bigint");
 
@@ -652,8 +703,6 @@ namespace LiteCharms.Features.MidrandBooks.Postgres.Migrations
 
                     b.HasIndex("OrderId");
 
-                    b.HasIndex("PaymentGatewayId");
-
                     b.HasIndex("PaymentId");
 
                     b.ToTable("Ledger", (string)null);
@@ -1062,6 +1111,25 @@ namespace LiteCharms.Features.MidrandBooks.Postgres.Migrations
                     b.Navigation("Order");
                 });
 
+            modelBuilder.Entity("LiteCharms.Features.MidrandBooks.Payments.Entities.PaymentGatewayLedger", b =>
+                {
+                    b.HasOne("LiteCharms.Features.MidrandBooks.Orders.Entities.Order", "Order")
+                        .WithMany()
+                        .HasForeignKey("OrderId")
+                        .OnDelete(DeleteBehavior.Cascade)
+                        .IsRequired();
+
+                    b.HasOne("LiteCharms.Features.MidrandBooks.Payments.Entities.Payment", "Payment")
+                        .WithMany()
+                        .HasForeignKey("PaymentId")
+                        .OnDelete(DeleteBehavior.Cascade)
+                        .IsRequired();
+
+                    b.Navigation("Order");
+
+                    b.Navigation("Payment");
+                });
+
             modelBuilder.Entity("LiteCharms.Features.MidrandBooks.Payments.Entities.PaymentLedger", b =>
                 {
                     b.HasOne("LiteCharms.Features.MidrandBooks.Customers.Entities.Customer", "Customer")
@@ -1076,11 +1144,6 @@ namespace LiteCharms.Features.MidrandBooks.Postgres.Migrations
                         .OnDelete(DeleteBehavior.Cascade)
                         .IsRequired();
 
-                    b.HasOne("LiteCharms.Features.MidrandBooks.Payments.Entities.PaymentGateway", "Gateway")
-                        .WithMany()
-                        .HasForeignKey("PaymentGatewayId")
-                        .OnDelete(DeleteBehavior.Cascade);
-
                     b.HasOne("LiteCharms.Features.MidrandBooks.Payments.Entities.Payment", "Payment")
                         .WithMany()
                         .HasForeignKey("PaymentId")
@@ -1089,8 +1152,6 @@ namespace LiteCharms.Features.MidrandBooks.Postgres.Migrations
 
                     b.Navigation("Customer");
 
-                    b.Navigation("Gateway");
-
                     b.Navigation("Order");
 
                     b.Navigation("Payment");

LiteCharms.Features.TechShop.Tests/LiteCharms.Features.TechShop.Tests.csproj

@@ -17,7 +17,7 @@
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
-    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.5.1" />
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.6.0" />
     <PackageReference Include="xunit" Version="2.9.3" />
     <PackageReference Include="xunit.runner.visualstudio" Version="3.1.5">
       <PrivateAssets>all</PrivateAssets>

LiteCharms.Features.TechShop/LiteCharms.Features.TechShop.csproj

@@ -105,7 +105,7 @@
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
-    <PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="10.0.1" />
+    <PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="10.0.2" />
 
     <!-- Global Usings -->
     <Using Include="Npgsql" />
@@ -116,8 +116,8 @@
 
   <!-- Email -->
   <ItemGroup>
-    <PackageReference Include="MailKit" Version="4.16.0" />
+    <PackageReference Include="MailKit" Version="4.17.0" />
-    <PackageReference Include="MimeKit" Version="4.16.0" />
+    <PackageReference Include="MimeKit" Version="4.17.0" />
 
     <!-- Global Usings-->
     <Using Include="MimeKit" />
@@ -136,8 +136,8 @@
 
   <!-- Amazon S3 SDK -->
   <ItemGroup>
-    <PackageReference Include="AWSSDK.Extensions.NetCore.Setup" Version="4.0.4.1" />
+    <PackageReference Include="AWSSDK.Extensions.NetCore.Setup" Version="4.0.4.3" />
-    <PackageReference Include="AWSSDK.S3" Version="4.0.23.4" />
+    <PackageReference Include="AWSSDK.S3" Version="4.0.24" />
     <ProjectReference Include="..\LiteCharms.Features\LiteCharms.Features.csproj" />
 
     <!-- global Usings -->

LiteCharms.Features.Tests/HashServiceFeatureTests.cs

@@ -1,13 +1,10 @@
 using LiteCharms.Features.Hasher;
-using LiteCharms.Features.Models;
-using static LiteCharms.Features.Extensions.Hash;
 
 namespace LiteCharms.Features.Tests;
 
 public class HashServiceFeatureTests(Fixture fixture) : IClassFixture<Fixture>
 {
     private readonly HashService hashService = fixture.Services.GetRequiredService<HashService>();
-    private readonly string payfastPassphrase = fixture.Configuration.GetSection("HasherSettings:PayfastPassphrase").Value!;
 
     [Fact]
     public void StringToSha256Hash_Should_GenerateHash()
@@ -62,28 +59,6 @@ public class HashServiceFeatureTests(Fixture fixture) : IClassFixture<Fixture>
         Assert.Equal(expectedMd5Lowercase, result.Value);
     }
 
-    [Fact]
-    public void VerifyPayfastWebhookSignature_Should_GenerateHash()
-    {
-        var paymentId = hashService.HashEncodeLongId(1001).Value;
-
-        var payload = new PayfastWebhookPayload
-        {
-            Amount = "350.00",
-            ItemName = "System Architecture Book",
-            MPaymentId = paymentId,            
-        };
-
-        var rawPayload = payload.ToRawPayfastPayload(payfastPassphrase);
-
-        var generatedSignature = HashService.ToMd5Hash(rawPayload).Value;
-
-        var result = hashService.VerifyPayfastWebhookSignature(payload, generatedSignature);
-
-        Assert.True(result.IsSuccess);
-        Assert.True(result.Value);
-    }
-
     [Fact]
     public void HashEncodeHex_Should_GenerateHash()
     {

LiteCharms.Features.Tests/LiteCharms.Features.Tests.csproj

@@ -17,7 +17,7 @@
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
-    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.5.1" />
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.6.0" />
     <PackageReference Include="xunit" Version="2.9.3" />
     <PackageReference Include="xunit.runner.visualstudio" Version="3.1.5">
       <PrivateAssets>all</PrivateAssets>

LiteCharms.Features/Enums.cs

@@ -19,6 +19,7 @@ public enum LedgerStatuses : int
     Cancelled = 4,
     Failed = 5,
     Partial = 6,
+    Completed = 7,
 }
 
 public enum PaymentStatuses : int

LiteCharms.Features/Extensions/Hash.cs

@@ -1,6 +1,5 @@
 using LiteCharms.Features.Hasher;
 using LiteCharms.Features.Hasher.Configuration;
-using LiteCharms.Features.Models;
 
 namespace LiteCharms.Features.Extensions;
 
@@ -21,65 +20,4 @@ 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);
-    }
 }

LiteCharms.Features/Hasher/HashService.cs

@@ -1,13 +1,9 @@
 using LiteCharms.Features.Abstractions;
-using LiteCharms.Features.Hasher.Configuration;
-using LiteCharms.Features.Models;
 
 namespace LiteCharms.Features.Hasher;
 
-public sealed partial class HashService(IHashids hasher, IOptions<HasherSettings> options) : IService
+public sealed partial class HashService(IHashids hasher) : IService
 {
-    private readonly HasherSettings settings = options.Value;
-
     [GeneratedRegex(@"\A\b[0-9a-fA-F]+\b\Z")]
     private static partial Regex HexHashRegex { get; }
 
@@ -41,44 +37,6 @@ public sealed partial class HashService(IHashids hasher, IOptions<HasherSettings
         return Result.Ok(Convert.ToHexString(bytes).ToLowerInvariant());
     }
 
-    public Result<bool> VerifyPayfastWebhookSignature(PayfastWebhookPayload payload, string incomingSignature)
-    {
-        try
-        {
-            if (string.IsNullOrWhiteSpace(incomingSignature))
-                return Result.Fail<bool>("Validation failed: Missing signature string parameter.");
-
-            var parameters = new List<string>();
-
-            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))
-                signatureString += $"&passphrase={WebUtility.UrlEncode(settings.PayfastPassphrase)}";
-
-            var localHashResult = ToMd5Hash(signatureString);
-
-            if (!localHashResult.IsSuccess)
-                return Result.Fail<bool>(localHashResult.Errors);
-
-            bool isValid = string.Equals(localHashResult.Value, incomingSignature, StringComparison.OrdinalIgnoreCase);
-
-            return Result.Ok(isValid);
-        }
-        catch (Exception ex)
-        {
-            return Result.Fail<bool>(new Error("An error occurred during Payfast MD5 verification.").CausedBy(ex));
-        }
-    }
-
     public Result<string> HashEncodeHex(string input) => string.IsNullOrWhiteSpace(input) || !HexHashRegex.IsMatch(input)
             ? Result.Fail<string>("Input must be a valid hexadecimal string.")
             : Result.Ok(hasher.EncodeHex(input));

LiteCharms.Features/LiteCharms.Features.csproj

@@ -32,7 +32,7 @@
   <!-- Quartz Scheduler-->
   <ItemGroup>    
     <PackageReference Include="Hashids.net" Version="1.7.0" />    
-    <PackageReference Include="Meziantou.Analyzer" Version="3.0.96">
+    <PackageReference Include="Meziantou.Analyzer" Version="3.0.98">
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>    
@@ -105,7 +105,7 @@
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
-    <PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="10.0.1" />
+    <PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="10.0.2" />
 
     <!-- Global Usings -->
     <Using Include="Npgsql" />
@@ -116,8 +116,8 @@
   
   <!-- Email -->
   <ItemGroup>
-    <PackageReference Include="MailKit" Version="4.16.0" />
+    <PackageReference Include="MailKit" Version="4.17.0" />
-    <PackageReference Include="MimeKit" Version="4.16.0" />
+    <PackageReference Include="MimeKit" Version="4.17.0" />
     
     <!-- Global Usings-->
     <Using Include="MimeKit" />
@@ -136,8 +136,8 @@
   
   <!-- Amazon S3 SDK -->
   <ItemGroup>
-    <PackageReference Include="AWSSDK.Extensions.NetCore.Setup" Version="4.0.4.1" />
+    <PackageReference Include="AWSSDK.Extensions.NetCore.Setup" Version="4.0.4.3" />
-    <PackageReference Include="AWSSDK.S3" Version="4.0.23.4" />
+    <PackageReference Include="AWSSDK.S3" Version="4.0.24" />
     
     <!-- global Usings -->
     <Using Include="Amazon.S3" />
@@ -147,6 +147,9 @@
 
   <!-- Shared Usings -->
   <ItemGroup>
+    <Using Include="System.Web" />
+    <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

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