Merge pull request 'Updated API to use LiteCharms Security' (#83) from payments into master

Reviewed-on: #83

.gitignore

@@ -360,4 +360,7 @@ MigrationBackup/
 .ionide/
 
 # Fody - auto-generated XML schema
-FodyWeavers.xsd
+FodyWeavers.xsd
+/LiteCharms.Features.Tests/http/http-client.env.json
+/LiteCharms.Features.Tests/http/midrandshop-api/http-client.env.json
+/LiteCharms.Features.Tests/http/authentik/http-client.env.json

LiteCharms.Features.MidrandBooks.Seed/CategorySeederService.cs

@@ -3,7 +3,7 @@ using LiteCharms.Features.MidrandBooks.Products;
 
 namespace LiteCharms.Features.MidrandBooks.Seed;
 
-public class CategorySeederService(CategoryService categoryService, ProductService productService, IFeatureManager features,
+public sealed class CategorySeederService(CategoryService categoryService, ProductService productService, IFeatureManager features,
     ILogger<CategorySeederService> logger) : BackgroundService
 {
     protected override async Task ExecuteAsync(CancellationToken stoppingToken)

LiteCharms.Features.MidrandBooks.Seed/Configuration/CdnSettings.cs

@@ -1,6 +1,6 @@
 namespace LiteCharms.Features.MidrandBooks.Seed.Configuration;
 
-public class CdnSettings
+public sealed class CdnSettings
 {
     public string? BaseCdn { get; set; }
 

LiteCharms.Features.MidrandBooks.Seed/CustomerSeederService.cs

@@ -5,7 +5,7 @@ using LiteCharms.Features.MidrandBooks.Orders.Models;
 
 namespace LiteCharms.Features.MidrandBooks.Seed;
 
-public class CustomerSeederService(CustomerService customerService, OrderService orderService, IFeatureManager features,
+public sealed class CustomerSeederService(CustomerService customerService, OrderService orderService, IFeatureManager features,
     ILogger<CustomerSeederService> logger) : BackgroundService
 {
     protected override async Task ExecuteAsync(CancellationToken stoppingToken)

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.S3" Version="4.0.23.4" />
+    <PackageReference Include="AWSSDK.Extensions.NetCore.Setup" Version="4.0.4.3" />
+    <PackageReference Include="AWSSDK.S3" Version="4.0.24" />
     <ProjectReference Include="..\LiteCharms.Features\LiteCharms.Features.csproj" />
 
     <!-- global Usings -->

LiteCharms.Features.MidrandBooks.Seed/ProductsSeederService.cs

@@ -5,7 +5,7 @@ using LiteCharms.Features.MidrandBooks.Seed.Configuration;
 
 namespace LiteCharms.Features.MidrandBooks.Seed;
 
-public class ProductsSeederService(ProductService productService, AuthorService authorService, BooksService booksService,
+public sealed class ProductsSeederService(ProductService productService, AuthorService authorService, BooksService booksService,
     IFeatureManager features, IOptions<CdnSettings> options, ILogger<ProductsSeederService> logger) : BackgroundService
 {
     private readonly CdnSettings cdnSettings = options.Value;

LiteCharms.Features.MidrandBooks.Seed/appsettings.json

@@ -1,6 +1,6 @@
 {
   "FeatureManagement": {
-    "CategorySeederService": true,
+    "CategorySeederService": false,
     "CustomerSeederService": false,
     "ProductsSeederService": false
   },

LiteCharms.Features.MidrandBooks.Tests/AuthorServiceFeatureTests.cs

@@ -5,7 +5,7 @@ using LiteCharms.Features.Models;
 
 namespace LiteCharms.Features.MidrandBooks.Tests;
 
-public class AuthorServiceFeatureTests(Fixture fixture, ITestOutputHelper output) : IClassFixture<Fixture>
+public class AuthorServiceFeatureTests(Fixture fixture) : IClassFixture<Fixture>
 {
     private readonly AuthorService authorService = fixture.Services.GetRequiredService<AuthorService>();
 

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

@@ -1,5 +1,4 @@
 using LiteCharms.Features.Extensions;
-using LiteCharms.Features.MidrandBooks.Abstractions;
 using LiteCharms.Features.MidrandBooks.Extensions;
 
 namespace LiteCharms.Features.MidrandBooks.Tests.Common;
@@ -25,7 +24,8 @@ public class Fixture : IDisposable
             .AddEnvironmentVariables()
             .Build();
 
-        Services = new ServiceCollection()            
+        Services = new ServiceCollection()
+            .AddHttpClient()
             .AddMediator()
             .AddLogging()
             .AddEmailServiceBus()
@@ -34,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, true, 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, true, 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/PaymentServiceFeatureTests.cs

@@ -0,0 +1,98 @@
+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 PaymentServiceFeatureTests(Fixture fixture) : IClassFixture<Fixture>
+{
+    private readonly PaymentService paymentService = fixture.Services.GetRequiredService<PaymentService>();
+
+    [IntegrationFact]
+    public async Task CreateRefundAsync_ShouldReturn_ResultWithRefundId()
+    {
+        var request = new CreateRefund
+        {
+            Amount = 50,
+            OrderId = 2,
+            Type = RefundTypes.Partial,
+            Reason = "Returned damaged book",
+            Status = RefundStatus.Completed,            
+        };
+
+        var result = await paymentService.CreateRefundAsync(request, fixture.CancellationToken);
+
+        Assert.True(result.IsSuccess);
+        Assert.True(result.Value > 0);
+    }
+
+    [IntegrationFact]
+    public async Task WriteLedgerEntryAsync_ShouldReturn_ResultWithSuccess()
+    {
+        var request = new CreateLedgerEntry
+        {
+            CustomerId = 1,
+            OrderId = 1,
+            PaymentGatewayId = 1,
+            PaymentGatewayReference = "TEST REFERENCE",
+            PaymentId = 1,
+            Status = LedgerStatuses.Received,
+        };
+
+        var result = await paymentService.WriteLedgerEntryAsync(request, fixture.CancellationToken);
+
+        Assert.True(result.IsSuccess);
+    }
+
+    [IntegrationFact]
+    public async Task GetPaymentGatewayAsync_ShouldReturn_ResultWithPaymentGateway()
+    {
+        var result = await paymentService.GetPaymentGatewayAsync(1, fixture.CancellationToken);
+
+        Assert.True(result.IsSuccess);
+        Assert.NotNull(result.Value);
+    }
+
+    [IntegrationFact]
+    public async Task CreatePaymentGatewayAsync_ShouldReturn_ResultWithGatewayId()
+    {
+        var request = new CreatePaymentGateway
+        {
+            IsSandbox = true,
+            MerchantId = "10049307",
+            MerchantKey = "ju6navn0jcbf0",
+            Name = "Payfast",
+            Website = "https://sandbox.payfast.co.za/eng/process",
+        };
+
+        var result = await paymentService.CreatePaymentGatewayAsync(request, fixture.CancellationToken);
+
+        Assert.True(result.IsSuccess);
+        Assert.True(result.Value > 0);
+    }
+
+    [IntegrationFact]
+    public async Task CompletePaymentAsync_ShouldReturn_ResultWithSuccess()
+    {
+        var result = await paymentService.CompletePaymentAsync(1, PaymentStatuses.Paid, fixture.CancellationToken);
+
+        Assert.True(result.IsSuccess);
+    }
+
+    [IntegrationFact]
+    public async Task UpdatePaymentAsync_ShouldReturn_ResultWithSuccess()
+    {
+        var result = await paymentService.UpdatePaymentAsync(1, 200, fixture.CancellationToken);
+
+        Assert.True(result.IsSuccess);
+    }
+
+    [IntegrationFact]
+    public async Task CreatePaymentAsync_ShouldReturn_ResultWithPaymentId()
+    {
+        var result = await paymentService.CreatePaymentAsync(100, 1, "HASHEDID", fixture.CancellationToken);
+
+        Assert.True(result.IsSuccess);
+        Assert.True(result.Value > 0);
+    }
+}

LiteCharms.Features.MidrandBooks.Tests/ProductServiceFeatureTests.cs

@@ -9,6 +9,47 @@ public class ProductServiceFeatureTests(Fixture fixture, ITestOutputHelper outpu
 {
     private readonly ProductService productService = fixture.Services.GetRequiredService<ProductService>();
 
+    [IntegrationFact]
+    public async Task CheckProductStockAvailabilityAsync_ShouldReturn_ResultWithProductInventory()
+    {
+        var result = await productService.CheckProductStockAvailabilityAsync(1, 1, fixture.CancellationToken);
+
+        Assert.True(result.IsSuccess);
+        Assert.NotNull(result.Value);
+    }
+
+    [IntegrationFact]
+    public async Task ReserveProductInventoryAsync_ShouldReturn_ResultWithSuccess()
+    {
+        var request = new ReserveStock
+        {
+            ProductId = 1,
+            ProductPriceId = 1,
+            Reservation = 100,            
+        };
+
+        var result = await productService.ReserveProductInventoryAsync(request, fixture.CancellationToken);
+
+        Assert.True(result.IsSuccess);
+        Assert.True(result.Value > 0);
+    }
+
+    [IntegrationFact]
+    public async Task AllocateProductInventoryAsync_ShouldReturn_ResultWithSuccess()
+    {
+        var request = new AllocateStock
+        {
+            ProductId = 1, 
+            ProductPriceId = 1,
+            Allocation = 500,
+        };
+
+        var result = await productService.AllocateProductInventoryAsync(request, fixture.CancellationToken);
+
+        Assert.True(result.IsSuccess);
+        Assert.True(result.Value > 0);
+    }
+
     [IntegrationFact]
     public async Task AddProductCategoryAsync_ShouldReturn_ResultWithId()
     {

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/Abstractions/IService.cs

@@ -1,3 +0,0 @@
-namespace LiteCharms.Features.MidrandBooks.Abstractions;
-
-public interface IService;

LiteCharms.Features.MidrandBooks/AuthorBooks/BooksService.cs

@@ -1,4 +1,4 @@
-using LiteCharms.Features.MidrandBooks.Abstractions;
+using LiteCharms.Features.Abstractions;
 using LiteCharms.Features.MidrandBooks.AuthorBooks.Models;
 using LiteCharms.Features.MidrandBooks.Extensions;
 using LiteCharms.Features.MidrandBooks.Postgres;

LiteCharms.Features.MidrandBooks/Authors/AuthorService.cs

@@ -1,4 +1,4 @@
-using LiteCharms.Features.MidrandBooks.Abstractions;
+using LiteCharms.Features.Abstractions;
 using LiteCharms.Features.MidrandBooks.Authors.Models;
 using LiteCharms.Features.MidrandBooks.Extensions;
 using LiteCharms.Features.MidrandBooks.Postgres;

LiteCharms.Features.MidrandBooks/Categories/CategoryService.cs

@@ -1,4 +1,4 @@
-using LiteCharms.Features.MidrandBooks.Abstractions;
+using LiteCharms.Features.Abstractions;
 using LiteCharms.Features.MidrandBooks.Categories.Models;
 using LiteCharms.Features.MidrandBooks.Extensions;
 using LiteCharms.Features.MidrandBooks.Postgres;

LiteCharms.Features.MidrandBooks/Customers/CustomerService.cs

@@ -1,4 +1,4 @@
-using LiteCharms.Features.MidrandBooks.Abstractions;
+using LiteCharms.Features.Abstractions;
 using LiteCharms.Features.MidrandBooks.Customers.Models;
 using LiteCharms.Features.MidrandBooks.Extensions;
 using LiteCharms.Features.MidrandBooks.Postgres;

LiteCharms.Features.MidrandBooks/Enums.cs

@@ -1,62 +0,0 @@
-namespace LiteCharms.Features.MidrandBooks;
-
-public enum PublisherTypes : int
-{
-    Individual = 0,
-    Company = 1,
-    Organization = 2,
-    SelfPublished = 3,
-    UniversityPress = 4,
-    GovernmentAgency = 5,
-    NonProfit = 6,
-    Independent = 7
-}
-
-public enum BookTypes : int
-{
-    Fiction = 0,
-    NonFiction = 1,
-    Academic = 2,
-    SelfHelp = 3,
-    Biography = 4,
-    Poetry = 5,
-    Children = 6,
-    YoungAdult = 7,
-    ScienceFiction = 8,
-    Fantasy = 9
-}
-
-public enum BookContentTypes : int
-{
-    Text = 0,
-    Image = 1,
-    Video = 2,
-    Audio = 3,
-    Interactive = 4,
-    Markdown = 5,
-    Html = 6,
-    Json = 7,
-    Yaml = 8
-}
-
-public enum BookPageTypes : int
-{
-    Cover = 0,
-    Preface = 1,
-    Introduction = 2,
-    Content = 3,
-    Closing = 4,
-    Referencer = 5,
-    Credits = 6,
-    BackCover = 7
-}
-
-public enum ProductTypes : int
-{
-    Book = 1,
-    Journal = 2,
-    Magazine = 3,
-    EBook = 4,
-    Audiobook = 5,
-    Accessory = 6
-}

LiteCharms.Features.MidrandBooks/Extensions/Mappers.cs

@@ -4,12 +4,86 @@ using LiteCharms.Features.MidrandBooks.Categories.Models;
 using LiteCharms.Features.MidrandBooks.Customers.Models;
 using LiteCharms.Features.MidrandBooks.Orders.Models;
 using LiteCharms.Features.MidrandBooks.Pages.Models;
+using LiteCharms.Features.MidrandBooks.Payments.Models;
 using LiteCharms.Features.MidrandBooks.Products.Models;
 
 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,
+        Amount = entity.Amount,
+        Id = entity.Id,
+        OrderId = entity.OrderId,
+        Reason = entity.Reason,
+        Status = entity.Status,
+        Type = entity.Type,
+        UpdatedAt = entity.UpdatedAt,        
+    };
+
+    public static PaymentLedger ToModel(this Payments.Entities.PaymentLedger entity) => new()
+    {
+        Id = entity.Id,
+        CreatedAt = entity.CreatedAt,
+        CustomerId = entity.CustomerId,
+        OrderId = entity.OrderId,
+        PaymentId = entity.PaymentId,
+        Status = entity.Status,
+        MerchantPaymentId = entity.MerchantPaymentId,
+    };
+
+    public static PaymentGateway ToModel(this Payments.Entities.PaymentGateway entity) => new()
+    {
+        Id = entity.Id,
+        CreatedAt = entity.CreatedAt,
+        UpdatedAt = entity.UpdatedAt,
+        Enabled = entity.Enabled,
+        IsSandbox = entity.IsSandbox,
+        MerchantId = entity.MerchantId,
+        MerchantKey = entity.MerchantKey,
+        Name = entity.Name,
+        Website = entity.Website,
+    };
+
+    public static Payment ToModel(this Payments.Entities.Payment entity) => new()
+    {
+        Id = entity.Id,
+        Amount = entity.Amount,
+        CreatedAt = entity.CreatedAt,
+        OrderId = entity.OrderId,
+        Reference = entity.Reference,
+        Status = entity.Status,
+        UpdatedAt = entity.UpdatedAt,        
+    };
+
+    public static ProductInventory ToModel(this Products.Entities.ProductInventory entity) => new()
+    {
+        Id = entity.Id,
+        CreatedAt = entity.CreatedAt,
+        ProductId = entity.ProductId,
+        ProductPriceId = entity.ProductPriceId,
+        Status = entity.Status,
+        TotalAllocated = entity.TotalAllocated,
+        TotalReserved = entity.TotalReserved,
+    };
+
     public static Category ToModel(this Categories.Entities.Category entity) => new()
     {
         Id = entity.Id,

LiteCharms.Features.MidrandBooks/Extensions/Shop.cs

@@ -1,4 +1,4 @@
-using LiteCharms.Features.MidrandBooks.Abstractions;
+using LiteCharms.Features.Abstractions;
 
 namespace LiteCharms.Features.MidrandBooks.Extensions;
 

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.S3" Version="4.0.23.4" />
+    <PackageReference Include="AWSSDK.Extensions.NetCore.Setup" Version="4.0.4.3" />
+    <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/Orders/OrderService.cs

@@ -1,4 +1,4 @@
-using LiteCharms.Features.MidrandBooks.Abstractions;
+using LiteCharms.Features.Abstractions;
 using LiteCharms.Features.MidrandBooks.Extensions;
 using LiteCharms.Features.MidrandBooks.Orders.Models;
 using LiteCharms.Features.MidrandBooks.Postgres;

LiteCharms.Features.MidrandBooks/Pages/PageService.cs

@@ -1,4 +1,4 @@
-using LiteCharms.Features.MidrandBooks.Abstractions;
+using LiteCharms.Features.Abstractions;
 using LiteCharms.Features.MidrandBooks.Extensions;
 using LiteCharms.Features.MidrandBooks.Pages.Models;
 using LiteCharms.Features.MidrandBooks.Postgres;

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

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

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

@@ -0,0 +1,22 @@
+namespace LiteCharms.Features.MidrandBooks.Payments.Entities;
+
+public sealed class PaymentConfiguration : IEntityTypeConfiguration<Payment>
+{
+    public void Configure(EntityTypeBuilder<Payment> builder)
+    {
+        builder.ToTable("Payments");
+
+        builder.HasKey(f => f.Id);
+        builder.Property(f => f.CreatedAt).IsRequired().ValueGeneratedOnAdd().HasDefaultValueSql("now()");
+        builder.Property(f => f.UpdatedAt);
+        builder.Property(f => f.Status).IsRequired();
+        builder.Property(f => f.Reference).IsRequired();
+        builder.Property(f => f.OrderId).IsRequired();
+        builder.Property(f => f.Amount).IsRequired().HasPrecision(18, 2);
+
+        builder.HasOne(f => f.Order)
+            .WithMany()
+            .HasForeignKey(f => f.OrderId)
+            .OnDelete(DeleteBehavior.Restrict);
+    }
+}

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

@@ -0,0 +1,4 @@
+namespace LiteCharms.Features.MidrandBooks.Payments.Entities;
+
+[EntityTypeConfiguration<PaymentGatewayConfiguration, PaymentGateway>]
+public class PaymentGateway : Models.PaymentGateway;

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

@@ -0,0 +1,19 @@
+namespace LiteCharms.Features.MidrandBooks.Payments.Entities;
+
+public sealed class PaymentGatewayConfiguration : IEntityTypeConfiguration<PaymentGateway>
+{
+    public void Configure(EntityTypeBuilder<PaymentGateway> builder)
+    {
+        builder.ToTable("Gateways");
+
+        builder.HasKey(f => f.Id);
+        builder.Property(f => f.CreatedAt).IsRequired().ValueGeneratedOnAdd().HasDefaultValueSql("now()");
+        builder.Property(f => f.UpdatedAt);
+        builder.Property(f => f.Website).IsRequired(false);
+        builder.Property(f => f.IsSandbox);
+        builder.Property(f => f.MerchantKey).IsRequired();
+        builder.Property(f => f.MerchantId).IsRequired();
+        builder.Property(f => f.Enabled);
+        builder.Property(f => f.Name).IsRequired();
+    }
+}

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

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

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

@@ -0,0 +1,34 @@
+namespace LiteCharms.Features.MidrandBooks.Payments.Entities;
+
+public sealed class PaymentLedgerConfiguration : IEntityTypeConfiguration<PaymentLedger>
+{
+    public void Configure(EntityTypeBuilder<PaymentLedger> builder)
+    {
+        builder.ToTable("Ledger");
+
+        builder.HasKey(f => f.Id);
+        builder.Property(f => f.CreatedAt).IsRequired().ValueGeneratedOnAdd().HasDefaultValueSql("now()");
+        builder.Property(f => f.Status).IsRequired();
+        builder.Property(f => f.MerchantPaymentId).IsRequired(false);
+        builder.Property(f => f.OrderId).IsRequired();
+        builder.Property(f => f.CustomerId).IsRequired();
+        builder.Property(f => f.PaymentId).IsRequired();
+
+        builder.HasOne(f => f.Payment)
+            .WithMany()
+            .IsRequired()
+            .HasForeignKey(f => f.PaymentId)
+            .OnDelete(DeleteBehavior.Cascade);
+
+        builder.HasOne(f => f.Order)
+            .WithMany()
+            .IsRequired()
+            .HasForeignKey(f => f.OrderId)
+            .OnDelete(DeleteBehavior.Cascade);
+
+        builder.HasOne(f => f.Customer)
+            .WithMany()
+            .IsRequired()
+            .HasForeignKey(f => f.CustomerId);
+    }
+}

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

@@ -0,0 +1,164 @@
+using LiteCharms.Features.Hasher;
+using LiteCharms.Features.Hasher.Configuration;
+using LiteCharms.Features.Mediator;
+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)
+    {
+        using var activity = MediatorTelemetry.Source.StartActivity($"Quartz: {typeof(PayfastPaymentConfirmationReceivedEvent).Name}");
+        activity?.SetTag("event.correlation_id", notification.CorrelationId);
+
+        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!, notification.AllowLoopback, 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);
+        }
+        activity?.SetStatus(ActivityStatusCode.Ok);
+
+    }
+}

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

@@ -0,0 +1,30 @@
+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 bool AllowLoopback { get; set; }
+
+    public PayfastPaymentConfirmationReceivedEvent() { }
+
+    private PayfastPaymentConfirmationReceivedEvent(PayfastWebhookPayload? payload, string paymentId, bool performBackgroundChecks = true, bool allowLoopback = false)
+    {
+        Payload = payload;
+        CorrelationId = paymentId;
+        PerformBackgroundChecks = performBackgroundChecks;
+        AllowLoopback = allowLoopback;
+    }
+
+    public static PayfastPaymentConfirmationReceivedEvent Create(PayfastWebhookPayload? payload, string paymentId, bool performBackgroundChecks = true, bool allowLoopback = false) =>
+        new(payload, paymentId, performBackgroundChecks, allowLoopback);
+}

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/Payment.cs

@@ -0,0 +1,18 @@
+namespace LiteCharms.Features.MidrandBooks.Payments.Models;
+
+public class Payment
+{
+    public long Id { get; set; }
+
+    public DateTime CreatedAt { get; set; }
+
+    public DateTime? UpdatedAt { get; set; }
+
+    public decimal Amount { get; set; }
+
+    public long OrderId { get; set; }
+
+    public string? Reference { get; set; }
+
+    public PaymentStatuses Status { get; set; }
+}

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

@@ -0,0 +1,22 @@
+namespace LiteCharms.Features.MidrandBooks.Payments.Models;
+
+public class PaymentGateway
+{
+    public long Id { get; set; }
+
+    public DateTime CreatedAt { get; set; }
+
+    public DateTime? UpdatedAt { get; set; }
+
+    public string? Name { get; set; }
+
+    public string? Website { get; set; }
+
+    public string? MerchantId { get; set; }
+
+    public string? MerchantKey { get; set; }
+
+    public bool IsSandbox { get; set; }
+
+    public bool Enabled { get; set; }
+}

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

@@ -0,0 +1,18 @@
+namespace LiteCharms.Features.MidrandBooks.Payments.Models;
+
+public class PaymentLedger
+{
+    public long Id { get; set; }
+
+    public DateTime CreatedAt { get; set; }
+
+    public LedgerStatuses Status { get; set; }
+
+    public long OrderId { get; set; }
+
+    public long PaymentId { get; set; }
+
+    public long CustomerId { get; set; }
+
+    public string? MerchantPaymentId { get; set; }
+}

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

@@ -0,0 +1,74 @@
+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; }
+
+    public RefundStatus Status { get; set; }
+
+    public string? Reason { get; set; }
+
+    public decimal Amount { get; set; }
+};
+
+public sealed record CreateRefund
+{
+    public long OrderId { get; set; }
+
+    public RefundTypes Type { get; set; }
+
+    public RefundStatus Status { get; set; }
+
+    public string? Reason { get; set; }
+
+    public decimal Amount { get; set; }
+}
+
+public sealed record CreateLedgerEntry
+{
+    public required LedgerStatuses Status { get; set; }
+
+    public required long OrderId { get; set; }
+
+    public required long PaymentId { get; set; }
+
+    public required long CustomerId { get; set; }
+
+    public string? PaymentGatewayReference { get; set; }
+
+    public long? PaymentGatewayId { get; set; }
+}
+
+public sealed record CreatePaymentGateway
+{
+    public required string? Name { get; set; }
+
+    public string? Website { get; set; }
+
+    public required string? MerchantId { get; set; }
+
+    public required string? MerchantKey { get; set; }
+
+    public bool IsSandbox { get; set; }
+}

LiteCharms.Features.MidrandBooks/Payments/PayfastService.cs

@@ -0,0 +1,177 @@
+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, bool allowLoopback = false, 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))
+            {
+                if (allowLoopback && IPAddress.IsLoopback(incomingIp))
+                {
+                    logger.LogInformation("Local development loopback IP '{RemoteIp}' allowed bypassing DNS verification.", remoteIpAddress);
+                    return Result.Ok(true);
+                }
+
+                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

@@ -1,7 +1,301 @@
-using LiteCharms.Features.MidrandBooks.Abstractions;
+using LiteCharms.Features.Abstractions;
+using LiteCharms.Features.MidrandBooks.Extensions;
+using LiteCharms.Features.MidrandBooks.Payments.Models;
+using LiteCharms.Features.MidrandBooks.Postgres;
 
 namespace LiteCharms.Features.MidrandBooks.Payments;
 
-public sealed class PaymentService : IService
+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
+        {
+            await using var context = await contextFactory.CreateDbContextAsync(cancellationToken);
+
+            var refund = await context.Refunds.AsNoTracking()
+                .FirstOrDefaultAsync(r => r.Id == refundId, cancellationToken);
+
+            return refund is not null
+                ? Result.Ok(refund.ToModel())
+                : Result.Fail<Refund>("Could not find refund");
+        }
+        catch (Exception ex)
+        {
+            return Result.Fail<Refund>(new Error(ex.Message).CausedBy(ex));
+        }
+    }
+
+    public async ValueTask<Result> UpdateRefundAsync(long refundId, UpdateRefund 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("Order not found");
+
+            var updatedRows = await context.Refunds
+                .Where(r => r.Id == refundId && r.OrderId == request.OrderId)
+                .ExecuteUpdateAsync(setters => setters
+                    .SetProperty(r => r.Status, request.Status)
+                    .SetProperty(r => r.Reason, request.Reason)
+                    .SetProperty(r => r.UpdatedAt, DateTime.UtcNow)
+                    .SetProperty(r => r.Amount, request.Amount), cancellationToken);
+
+            return updatedRows > 0
+                ? Result.Ok()
+                : Result.Fail("Failed to update refund");
+        }
+        catch (Exception ex)
+        {
+            return Result.Fail(new Error(ex.Message).CausedBy(ex));
+        }
+    }
+
+    public async ValueTask<Result<long>> CreateRefundAsync(CreateRefund request, CancellationToken cancellationToken = default)
+    {
+        try
+        {
+            await using var context = await contextFactory.CreateDbContextAsync(cancellationToken);
+
+            var order = await context.Orders.AsNoTracking()
+                .FirstOrDefaultAsync(o => o.Id == request.OrderId
+                    && o.Status == OrderStatus.Completed, cancellationToken);
+
+            if (order is null) return Result.Fail("Order not found");
+
+            if (request.Amount > order.Total)
+                return Result.Fail<long>("Refund amount cannot be greater than order total");
+
+            var totalRefundsPaid = await context.Refunds
+                .Where(r => r.OrderId == request.OrderId)
+                .SumAsync(r => r.Amount, cancellationToken);
+
+            if (request.Amount > (order.Total - totalRefundsPaid))
+                return Result.Fail<long>("Refund amount exceeds amount available for refund");
+
+            var refund = context.Refunds.Add(new Entities.Refund
+            {
+                Amount = request.Amount,
+                CreatedAt = DateTime.UtcNow,
+                OrderId = request.OrderId,
+                Reason = request.Reason,
+                Status = request.Status,
+                Type = request.Type,
+            });
+
+            return await context.SaveChangesAsync(cancellationToken) > 0
+                ? Result.Ok(refund.Entity.Id)
+                : Result.Fail<long>("Failed to create refund");
+        }
+        catch (Exception ex)
+        {
+            return Result.Fail(new Error(ex.Message).CausedBy(ex));
+        }
+    }
+
+    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
+        {
+            await using var context = await contextFactory.CreateDbContextAsync(cancellationToken);
+
+            if (!await context.Orders.AnyAsync(o => o.Id == request.OrderId, cancellationToken))
+                return Result.Fail("Order not found");
+
+            if (!await context.Customers.AnyAsync(o => o.Id == request.CustomerId, cancellationToken))
+                return Result.Fail("Customer not found");
+
+            if (!await context.Orders.AnyAsync(oc => oc.Id == request.OrderId && oc.CustomerId == request.CustomerId, cancellationToken))
+                return Result.Fail("Customer does not match the order");
+
+            if (!await context.Payments.AnyAsync(o => o.Id == request.PaymentId && o.OrderId == request.OrderId, cancellationToken))
+                return Result.Fail("Payment not found");
+
+            if (request.PaymentGatewayId is not null)
+                if (!await context.Gateways.AnyAsync(o => o.Id == request.PaymentGatewayId, cancellationToken))
+                    return Result.Fail("Gateway not found");
+
+            context.Ledger.Add(new Entities.PaymentLedger
+            {
+                CreatedAt = DateTime.UtcNow,
+                CustomerId = request.CustomerId,
+                OrderId = request.OrderId,
+                PaymentId = request.PaymentId,
+                Status = request.Status,
+            });
+
+            return await context.SaveChangesAsync(cancellationToken) > 0
+                ? Result.Ok()
+                : Result.Fail("Failed to create ledger entry");
+        }
+        catch (Exception ex)
+        {
+            return Result.Fail(new Error(ex.Message).CausedBy(ex));
+        }
+    }
+
+    public async ValueTask<Result<PaymentGateway>> GetPaymentGatewayAsync(long paymentGatewayId, CancellationToken cancellationToken = default)
+    {
+        try
+        {
+            await using var context = await contextFactory.CreateDbContextAsync(cancellationToken);
+
+            var gateway = await context.Gateways.AsNoTracking().FirstOrDefaultAsync(g => g.Id == paymentGatewayId, cancellationToken);
+
+            return gateway is not null
+                ? Result.Ok(gateway.ToModel())
+                : Result.Fail<PaymentGateway>("Could not find gateway");
+        }
+        catch (Exception ex)
+        {
+            return Result.Fail<PaymentGateway>(new Error(ex.Message).CausedBy(ex));
+        }
+    }
+
+    public async ValueTask<Result<long>> CreatePaymentGatewayAsync(CreatePaymentGateway request, CancellationToken cancellationToken = default)
+    {
+        try
+        {
+            await using var context = await contextFactory.CreateDbContextAsync(cancellationToken);
+
+            if (await context.Gateways.AnyAsync(g => g.MerchantId == request.MerchantId && g.MerchantKey == request.MerchantKey, cancellationToken))
+                return Result.Fail<long>("A gateway with the same credentials already exists");
+
+            var gateway = context.Gateways.Add(new Entities.PaymentGateway
+            {
+                CreatedAt = DateTime.UtcNow,
+                Enabled = true,
+                IsSandbox = request.IsSandbox,
+                MerchantId = request.MerchantId,
+                MerchantKey = request.MerchantKey,
+                Name = request.Name,
+                Website = request.Website,
+            });
+
+            return await context.SaveChangesAsync(cancellationToken) > 0
+                ? Result.Ok(gateway.Entity.Id)
+                : Result.Fail<long>("Failed to create payment gateway");
+        }
+        catch (Exception ex)
+        {
+            return Result.Fail<long>(new Error(ex.Message).CausedBy(ex));
+        }
+    }
+
+    public async ValueTask<Result> CompletePaymentAsync(long paymentId, PaymentStatuses status, CancellationToken cancellationToken = default)
+    {
+        try
+        {
+            await using var context = await contextFactory.CreateDbContextAsync(cancellationToken);
+
+            if (status == PaymentStatuses.NotPaid)
+                return Result.Fail("Cannot finalise a payment using NotPaid status");
+
+            var updatedRecords = await context.Payments
+                .Where(p => p.Id == paymentId && p.Status != PaymentStatuses.Paid && p.Status != status)
+                .ExecuteUpdateAsync(setters => setters
+                    .SetProperty(u => u.Status, status)
+                    .SetProperty(u => u.UpdatedAt, DateTime.UtcNow), cancellationToken);
+
+            return updatedRecords > 0
+                ? Result.Ok()
+                : Result.Fail("Failed to update payment");
+        }
+        catch (Exception ex)
+        {
+            return Result.Fail(new Error(ex.Message).CausedBy(ex));
+        }
+    }
+
+    public async ValueTask<Result> UpdatePaymentAsync(long paymentId, decimal amount, CancellationToken cancellationToken = default)
+    {
+        try
+        {
+            await using var context = await contextFactory.CreateDbContextAsync(cancellationToken);
+
+            var updatedRecords = await context.Payments
+                .Where(p => p.Id == paymentId && p.Status == PaymentStatuses.NotPaid)
+                .ExecuteUpdateAsync(setters => setters
+                    .SetProperty(u => u.Amount, amount)
+                    .SetProperty(u => u.Status, PaymentStatuses.NotPaid)
+                    .SetProperty(u => u.UpdatedAt, DateTime.UtcNow), cancellationToken);
+
+            return updatedRecords > 0
+                ? Result.Ok()
+                : Result.Fail("Failed to update payment");
+        }
+        catch (Exception ex)
+        {
+            return Result.Fail(new Error(ex.Message).CausedBy(ex));
+        }
+    }
+
+    public async ValueTask<Result<long>> CreatePaymentAsync(decimal amount, long orderId, string reference, CancellationToken cancellationToken = default)
+    {
+        try
+        {
+            await using var context = await contextFactory.CreateDbContextAsync(cancellationToken);
+
+            if (await context.Payments.AnyAsync(p => p.OrderId == orderId && p.Amount == amount && p.Status != PaymentStatuses.Paid, cancellationToken))
+                return Result.Fail<long>("An order with the same amount already exists in the system");
+
+            var payment = context.Payments.Add(new Entities.Payment
+            {
+                CreatedAt = DateTime.UtcNow,
+                Amount = amount,
+                OrderId = orderId,
+                Reference = reference,
+                Status = PaymentStatuses.NotPaid,
+            });
+
+            return await context.SaveChangesAsync(cancellationToken) > 0
+                ? Result.Ok(payment.Entity.Id)
+                : Result.Fail<long>("Failed to make payment");
+        }
+        catch (Exception ex)
+        {
+            return Result.Fail<long>(new Error(ex.Message).CausedBy(ex));
+        }
+    }
 }

LiteCharms.Features.MidrandBooks/Postgres/MidrandBooksDbContext.cs

@@ -40,4 +40,14 @@ public sealed class MidrandBooksDbContext(DbContextOptions<MidrandBooksDbContext
     public DbSet<Category> Categories => Set<Category>();
 
     public DbSet<ProductCategory> ProductCategories => Set<ProductCategory>();
+
+    public DbSet<ProductInventory> Inventories => Set<ProductInventory>();
+
+    public DbSet<Payment> Payments => Set<Payment>();
+
+    public DbSet<PaymentGateway> Gateways => Set<PaymentGateway>();
+
+    public DbSet<PaymentLedger> Ledger => Set<PaymentLedger>();
+
+    public DbSet<PaymentGatewayLedger> GatewayLedger => Set<PaymentGatewayLedger>();
 }

LiteCharms.Features.MidrandBooks/Postgres/Migrations/20260531094401_AddedPaymentObjects.cs

@@ -0,0 +1,185 @@
+using System;
+using Microsoft.EntityFrameworkCore.Migrations;
+using Npgsql.EntityFrameworkCore.PostgreSQL.Metadata;
+
+#nullable disable
+
+namespace LiteCharms.Features.MidrandBooks.Postgres.Migrations
+{
+    /// <inheritdoc />
+    public partial class AddedPaymentObjects : Migration
+    {
+        /// <inheritdoc />
+        protected override void Up(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.CreateTable(
+                name: "Gateways",
+                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()"),
+                    UpdatedAt = table.Column<DateTime>(type: "timestamp with time zone", nullable: true),
+                    Name = table.Column<string>(type: "text", nullable: false),
+                    Website = table.Column<string>(type: "text", nullable: true),
+                    MerchantId = table.Column<string>(type: "text", nullable: false),
+                    MerchantKey = table.Column<string>(type: "text", nullable: false),
+                    Passphrase = table.Column<string>(type: "text", nullable: false),
+                    IsSandbox = table.Column<bool>(type: "boolean", nullable: false),
+                    Enabled = table.Column<bool>(type: "boolean", nullable: false)
+                },
+                constraints: table =>
+                {
+                    table.PrimaryKey("PK_Gateways", x => x.Id);
+                });
+
+            migrationBuilder.CreateTable(
+                name: "Inventories",
+                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()"),
+                    Status = table.Column<int>(type: "integer", nullable: false),
+                    ProductId = table.Column<long>(type: "bigint", nullable: false),
+                    ProductPriceId = table.Column<long>(type: "bigint", nullable: false),
+                    TotalAllocated = table.Column<int>(type: "integer", nullable: false),
+                    TotalReserved = table.Column<int>(type: "integer", nullable: false)
+                },
+                constraints: table =>
+                {
+                    table.PrimaryKey("PK_Inventories", x => x.Id);
+                    table.ForeignKey(
+                        name: "FK_Inventories_Prices_ProductPriceId",
+                        column: x => x.ProductPriceId,
+                        principalTable: "Prices",
+                        principalColumn: "Id",
+                        onDelete: ReferentialAction.Cascade);
+                    table.ForeignKey(
+                        name: "FK_Inventories_Products_ProductId",
+                        column: x => x.ProductId,
+                        principalTable: "Products",
+                        principalColumn: "Id",
+                        onDelete: ReferentialAction.Cascade);
+                });
+
+            migrationBuilder.CreateTable(
+                name: "Payments",
+                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()"),
+                    UpdatedAt = table.Column<DateTime>(type: "timestamp with time zone", nullable: true),
+                    Amount = table.Column<decimal>(type: "numeric(18,2)", precision: 18, scale: 2, nullable: false),
+                    OrderId = table.Column<long>(type: "bigint", nullable: false),
+                    Reference = table.Column<string>(type: "text", nullable: false),
+                    Status = table.Column<int>(type: "integer", nullable: false)
+                },
+                constraints: table =>
+                {
+                    table.PrimaryKey("PK_Payments", x => x.Id);
+                    table.ForeignKey(
+                        name: "FK_Payments_Orders_OrderId",
+                        column: x => x.OrderId,
+                        principalTable: "Orders",
+                        principalColumn: "Id",
+                        onDelete: ReferentialAction.Restrict);
+                });
+
+            migrationBuilder.CreateTable(
+                name: "Ledger",
+                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()"),
+                    Status = table.Column<int>(type: "integer", nullable: false),
+                    OrderId = table.Column<long>(type: "bigint", nullable: false),
+                    PaymentId = table.Column<long>(type: "bigint", nullable: false),
+                    CustomerId = table.Column<long>(type: "bigint", nullable: false),
+                    PaymentGatewayReference = table.Column<string>(type: "text", nullable: true),
+                    PaymentGatewayId = table.Column<long>(type: "bigint", nullable: true)
+                },
+                constraints: table =>
+                {
+                    table.PrimaryKey("PK_Ledger", x => x.Id);
+                    table.ForeignKey(
+                        name: "FK_Ledger_Customers_CustomerId",
+                        column: x => x.CustomerId,
+                        principalTable: "Customers",
+                        principalColumn: "Id",
+                        onDelete: ReferentialAction.Cascade);
+                    table.ForeignKey(
+                        name: "FK_Ledger_Gateways_PaymentGatewayId",
+                        column: x => x.PaymentGatewayId,
+                        principalTable: "Gateways",
+                        principalColumn: "Id",
+                        onDelete: ReferentialAction.Cascade);
+                    table.ForeignKey(
+                        name: "FK_Ledger_Orders_OrderId",
+                        column: x => x.OrderId,
+                        principalTable: "Orders",
+                        principalColumn: "Id",
+                        onDelete: ReferentialAction.Cascade);
+                    table.ForeignKey(
+                        name: "FK_Ledger_Payments_PaymentId",
+                        column: x => x.PaymentId,
+                        principalTable: "Payments",
+                        principalColumn: "Id",
+                        onDelete: ReferentialAction.Cascade);
+                });
+
+            migrationBuilder.CreateIndex(
+                name: "IX_Inventories_ProductId",
+                table: "Inventories",
+                column: "ProductId");
+
+            migrationBuilder.CreateIndex(
+                name: "IX_Inventories_ProductPriceId",
+                table: "Inventories",
+                column: "ProductPriceId");
+
+            migrationBuilder.CreateIndex(
+                name: "IX_Ledger_CustomerId",
+                table: "Ledger",
+                column: "CustomerId");
+
+            migrationBuilder.CreateIndex(
+                name: "IX_Ledger_OrderId",
+                table: "Ledger",
+                column: "OrderId");
+
+            migrationBuilder.CreateIndex(
+                name: "IX_Ledger_PaymentGatewayId",
+                table: "Ledger",
+                column: "PaymentGatewayId");
+
+            migrationBuilder.CreateIndex(
+                name: "IX_Ledger_PaymentId",
+                table: "Ledger",
+                column: "PaymentId");
+
+            migrationBuilder.CreateIndex(
+                name: "IX_Payments_OrderId",
+                table: "Payments",
+                column: "OrderId");
+        }
+
+        /// <inheritdoc />
+        protected override void Down(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.DropTable(
+                name: "Inventories");
+
+            migrationBuilder.DropTable(
+                name: "Ledger");
+
+            migrationBuilder.DropTable(
+                name: "Gateways");
+
+            migrationBuilder.DropTable(
+                name: "Payments");
+        }
+    }
+}

LiteCharms.Features.MidrandBooks/Postgres/Migrations/20260601071804_RemovedPassphraseFromPaymentGateway.cs

@@ -0,0 +1,29 @@
+using Microsoft.EntityFrameworkCore.Migrations;
+
+#nullable disable
+
+namespace LiteCharms.Features.MidrandBooks.Postgres.Migrations
+{
+    /// <inheritdoc />
+    public partial class RemovedPassphraseFromPaymentGateway : Migration
+    {
+        /// <inheritdoc />
+        protected override void Up(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.DropColumn(
+                name: "Passphrase",
+                table: "Gateways");
+        }
+
+        /// <inheritdoc />
+        protected override void Down(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.AddColumn<string>(
+                name: "Passphrase",
+                table: "Gateways",
+                type: "text",
+                nullable: false,
+                defaultValue: "");
+        }
+    }
+}

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

@@ -536,6 +536,178 @@ namespace LiteCharms.Features.MidrandBooks.Postgres.Migrations
                     b.ToTable("BookPages", (string)null);
                 });
 
+            modelBuilder.Entity("LiteCharms.Features.MidrandBooks.Payments.Entities.Payment", b =>
+                {
+                    b.Property<long>("Id")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("bigint");
+
+                    NpgsqlPropertyBuilderExtensions.UseIdentityByDefaultColumn(b.Property<long>("Id"));
+
+                    b.Property<decimal>("Amount")
+                        .HasPrecision(18, 2)
+                        .HasColumnType("numeric(18,2)");
+
+                    b.Property<DateTime>("CreatedAt")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("timestamp with time zone")
+                        .HasDefaultValueSql("now()");
+
+                    b.Property<long>("OrderId")
+                        .HasColumnType("bigint");
+
+                    b.Property<string>("Reference")
+                        .IsRequired()
+                        .HasColumnType("text");
+
+                    b.Property<int>("Status")
+                        .HasColumnType("integer");
+
+                    b.Property<DateTime?>("UpdatedAt")
+                        .HasColumnType("timestamp with time zone");
+
+                    b.HasKey("Id");
+
+                    b.HasIndex("OrderId");
+
+                    b.ToTable("Payments", (string)null);
+                });
+
+            modelBuilder.Entity("LiteCharms.Features.MidrandBooks.Payments.Entities.PaymentGateway", b =>
+                {
+                    b.Property<long>("Id")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("bigint");
+
+                    NpgsqlPropertyBuilderExtensions.UseIdentityByDefaultColumn(b.Property<long>("Id"));
+
+                    b.Property<DateTime>("CreatedAt")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("timestamp with time zone")
+                        .HasDefaultValueSql("now()");
+
+                    b.Property<bool>("Enabled")
+                        .HasColumnType("boolean");
+
+                    b.Property<bool>("IsSandbox")
+                        .HasColumnType("boolean");
+
+                    b.Property<string>("MerchantId")
+                        .IsRequired()
+                        .HasColumnType("text");
+
+                    b.Property<string>("MerchantKey")
+                        .IsRequired()
+                        .HasColumnType("text");
+
+                    b.Property<string>("Name")
+                        .IsRequired()
+                        .HasColumnType("text");
+
+                    b.Property<DateTime?>("UpdatedAt")
+                        .HasColumnType("timestamp with time zone");
+
+                    b.Property<string>("Website")
+                        .HasColumnType("text");
+
+                    b.HasKey("Id");
+
+                    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")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("bigint");
+
+                    NpgsqlPropertyBuilderExtensions.UseIdentityByDefaultColumn(b.Property<long>("Id"));
+
+                    b.Property<DateTime>("CreatedAt")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("timestamp with time zone")
+                        .HasDefaultValueSql("now()");
+
+                    b.Property<long>("CustomerId")
+                        .HasColumnType("bigint");
+
+                    b.Property<string>("MerchantPaymentId")
+                        .HasColumnType("text");
+
+                    b.Property<long>("OrderId")
+                        .HasColumnType("bigint");
+
+                    b.Property<long>("PaymentId")
+                        .HasColumnType("bigint");
+
+                    b.Property<int>("Status")
+                        .HasColumnType("integer");
+
+                    b.HasKey("Id");
+
+                    b.HasIndex("CustomerId");
+
+                    b.HasIndex("OrderId");
+
+                    b.HasIndex("PaymentId");
+
+                    b.ToTable("Ledger", (string)null);
+                });
+
             modelBuilder.Entity("LiteCharms.Features.MidrandBooks.Payments.Entities.Refund", b =>
                 {
                     b.Property<long>("Id")
@@ -653,6 +825,43 @@ namespace LiteCharms.Features.MidrandBooks.Postgres.Migrations
                     b.ToTable("ProductCategories", (string)null);
                 });
 
+            modelBuilder.Entity("LiteCharms.Features.MidrandBooks.Products.Entities.ProductInventory", b =>
+                {
+                    b.Property<long>("Id")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("bigint");
+
+                    NpgsqlPropertyBuilderExtensions.UseIdentityByDefaultColumn(b.Property<long>("Id"));
+
+                    b.Property<DateTime>("CreatedAt")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("timestamp with time zone")
+                        .HasDefaultValueSql("now()");
+
+                    b.Property<long>("ProductId")
+                        .HasColumnType("bigint");
+
+                    b.Property<long>("ProductPriceId")
+                        .HasColumnType("bigint");
+
+                    b.Property<int>("Status")
+                        .HasColumnType("integer");
+
+                    b.Property<int>("TotalAllocated")
+                        .HasColumnType("integer");
+
+                    b.Property<int>("TotalReserved")
+                        .HasColumnType("integer");
+
+                    b.HasKey("Id");
+
+                    b.HasIndex("ProductId");
+
+                    b.HasIndex("ProductPriceId");
+
+                    b.ToTable("Inventories", (string)null);
+                });
+
             modelBuilder.Entity("LiteCharms.Features.MidrandBooks.Products.Entities.ProductPrice", b =>
                 {
                     b.Property<long>("Id")
@@ -891,6 +1100,63 @@ namespace LiteCharms.Features.MidrandBooks.Postgres.Migrations
                     b.Navigation("References");
                 });
 
+            modelBuilder.Entity("LiteCharms.Features.MidrandBooks.Payments.Entities.Payment", b =>
+                {
+                    b.HasOne("LiteCharms.Features.MidrandBooks.Orders.Entities.Order", "Order")
+                        .WithMany()
+                        .HasForeignKey("OrderId")
+                        .OnDelete(DeleteBehavior.Restrict)
+                        .IsRequired();
+
+                    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")
+                        .WithMany()
+                        .HasForeignKey("CustomerId")
+                        .OnDelete(DeleteBehavior.Cascade)
+                        .IsRequired();
+
+                    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("Customer");
+
+                    b.Navigation("Order");
+
+                    b.Navigation("Payment");
+                });
+
             modelBuilder.Entity("LiteCharms.Features.MidrandBooks.Payments.Entities.Refund", b =>
                 {
                     b.HasOne("LiteCharms.Features.MidrandBooks.Orders.Entities.Order", "Order")
@@ -950,6 +1216,25 @@ namespace LiteCharms.Features.MidrandBooks.Postgres.Migrations
                     b.Navigation("Product");
                 });
 
+            modelBuilder.Entity("LiteCharms.Features.MidrandBooks.Products.Entities.ProductInventory", b =>
+                {
+                    b.HasOne("LiteCharms.Features.MidrandBooks.Products.Entities.Product", "Product")
+                        .WithMany()
+                        .HasForeignKey("ProductId")
+                        .OnDelete(DeleteBehavior.Cascade)
+                        .IsRequired();
+
+                    b.HasOne("LiteCharms.Features.MidrandBooks.Products.Entities.ProductPrice", "Price")
+                        .WithMany()
+                        .HasForeignKey("ProductPriceId")
+                        .OnDelete(DeleteBehavior.Cascade)
+                        .IsRequired();
+
+                    b.Navigation("Price");
+
+                    b.Navigation("Product");
+                });
+
             modelBuilder.Entity("LiteCharms.Features.MidrandBooks.Products.Entities.ProductPrice", b =>
                 {
                     b.HasOne("LiteCharms.Features.MidrandBooks.Products.Entities.Product", "Product")

LiteCharms.Features.MidrandBooks/Products/Entities/ProductInventory.cs

@@ -0,0 +1,9 @@
+namespace LiteCharms.Features.MidrandBooks.Products.Entities;
+
+[EntityTypeConfiguration<ProductInventoryConfiguration, ProductInventory>]
+public class ProductInventory : Models.ProductInventory
+{
+    public virtual Product? Product { get; set; }
+
+    public virtual ProductPrice? Price { get; set; }
+}

LiteCharms.Features.MidrandBooks/Products/Entities/ProductInventoryConfiguration.cs

@@ -0,0 +1,27 @@
+namespace LiteCharms.Features.MidrandBooks.Products.Entities;
+
+public sealed class ProductInventoryConfiguration : IEntityTypeConfiguration<ProductInventory>
+{
+    public void Configure(EntityTypeBuilder<ProductInventory> builder)
+    {
+        builder.ToTable("Inventories");
+
+        builder.HasKey(f => f.Id);
+        builder.Property(f => f.CreatedAt).IsRequired().ValueGeneratedOnAdd().HasDefaultValueSql("now()");
+        builder.Property(f => f.Status).IsRequired();        
+        builder.Property(f => f.TotalAllocated).IsRequired();        
+        builder.Property(f => f.TotalReserved).IsRequired();        
+        builder.Property(f => f.ProductId).IsRequired();
+        builder.Property(f => f.ProductPriceId).IsRequired();
+
+        builder.HasOne(f => f.Product)
+            .WithMany()
+            .HasForeignKey(f => f.ProductId)
+            .OnDelete(DeleteBehavior.Cascade);
+
+        builder.HasOne(f => f.Price)
+            .WithMany()
+            .HasForeignKey(f => f.ProductPriceId)
+            .OnDelete(DeleteBehavior.Cascade);
+    }
+}

LiteCharms.Features.MidrandBooks/Products/Models/ProductInventory.cs

@@ -0,0 +1,18 @@
+namespace LiteCharms.Features.MidrandBooks.Products.Models;
+
+public class ProductInventory
+{
+    public long Id { get; set; }
+
+    public DateTime CreatedAt { get; set; }
+
+    public InventoryStatuses Status { get; set; }
+
+    public long ProductId { get; set; }
+
+    public long ProductPriceId { get; set; }
+
+    public int TotalAllocated { get; set; }
+
+    public int TotalReserved { get; set; }
+}

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

@@ -2,6 +2,24 @@
 
 namespace LiteCharms.Features.MidrandBooks.Products.Models;
 
+public sealed record ReserveStock
+{
+    public required long ProductId { get; set; }
+
+    public required long ProductPriceId { get; set; }
+
+    public int Reservation { get; set; }
+}
+
+public sealed record AllocateStock
+{
+    public required long ProductId { get; set; }
+
+    public required long ProductPriceId { get; set; }
+
+    public int Allocation { get; set; }
+}
+
 public sealed record CreateProduct
 {
     public required ProductTypes Type { get; set; }

LiteCharms.Features.MidrandBooks/Products/ProductService.cs

@@ -1,14 +1,132 @@
-using LiteCharms.Features.MidrandBooks.Abstractions;
+using LiteCharms.Features.Abstractions;
 using LiteCharms.Features.MidrandBooks.Categories.Models;
 using LiteCharms.Features.MidrandBooks.Extensions;
 using LiteCharms.Features.MidrandBooks.Postgres;
 using LiteCharms.Features.MidrandBooks.Products.Models;
 using LiteCharms.Features.Models;
+using Org.BouncyCastle.Asn1.Ocsp;
 
 namespace LiteCharms.Features.MidrandBooks.Products;
 
 public sealed class ProductService(IDbContextFactory<MidrandBooksDbContext> contextFactory) : IService
 {
+    public async ValueTask<Result<ProductInventory>> CheckProductStockAvailabilityAsync(long productId, long productPriceId, CancellationToken cancellationToken = default)
+    {
+        try
+        {
+            await using var context = await contextFactory.CreateDbContextAsync(cancellationToken);
+
+            var inventory = await context.Inventories
+                .AsNoTracking()
+                .Where(i => i.ProductPriceId == productPriceId && i.ProductId == productId)
+                .OrderByDescending(o => o.Id)
+                .FirstOrDefaultAsync(cancellationToken);
+
+            return inventory is not null
+                ? Result.Ok(inventory.ToModel())
+                : Result.Fail<ProductInventory>("Product sold out");
+        }
+        catch (Exception ex)
+        {
+            return Result.Fail<ProductInventory>(new Error(ex.Message).CausedBy(ex));
+        }
+    }
+
+    public async ValueTask<Result<long>> ReserveProductInventoryAsync(ReserveStock request, CancellationToken cancellationToken = default)
+    {
+        try
+        {
+            await using var context = await contextFactory.CreateDbContextAsync(cancellationToken);
+
+            var oldInventory = await context.Inventories
+                .AsNoTracking()
+                .Where(i => i.ProductPriceId == request.ProductPriceId && i.ProductId == request.ProductId)
+                .OrderByDescending(o => o.Id)
+                .FirstOrDefaultAsync(cancellationToken);
+
+            var newAllocation = 0;
+            var newReservation = 0;
+
+            if (oldInventory is not null)
+            {
+                newAllocation = oldInventory.TotalAllocated;
+                newReservation = oldInventory.TotalReserved + request.Reservation;
+            }
+            else
+            {
+                newAllocation = 0;
+                newReservation = request.Reservation;
+            }
+
+            if (newAllocation - newReservation < 0)
+                return Result.Fail<long>("Allocation failure: The requested book quantity exceeds current physical inventory availability.");
+
+            var inventory = context.Inventories.Add(new Entities.ProductInventory
+            {
+                CreatedAt = DateTime.UtcNow,
+                ProductId = request.ProductId,
+                ProductPriceId = request.ProductPriceId,
+                Status = InventoryStatuses.Reserved,
+                TotalAllocated = newAllocation,
+                TotalReserved = newReservation,
+            });
+
+            return await context.SaveChangesAsync(cancellationToken) > 0
+                ? Result.Ok(inventory.Entity.Id)
+                : Result.Fail<long>("Failed to create inventory entry");
+        }
+        catch (Exception ex)
+        {
+            return Result.Fail<long>(new Error(ex.Message).CausedBy(ex));
+        }
+    }
+
+    public async ValueTask<Result<long>> AllocateProductInventoryAsync(AllocateStock request, CancellationToken cancellationToken = default)
+    {
+        try
+        {
+            await using var context = await contextFactory.CreateDbContextAsync(cancellationToken);
+
+            var oldInventory = await context.Inventories
+                .AsNoTracking()
+                .Where(i => i.ProductPriceId == request.ProductPriceId && i.ProductId == request.ProductId)
+                .OrderByDescending(o => o.Id)
+                .FirstOrDefaultAsync(cancellationToken);
+
+            var newAllocation = 0;
+            var newReservation = 0;
+
+            if (oldInventory is not null)
+            {
+                newAllocation = oldInventory.TotalAllocated + request.Allocation;
+                newReservation = oldInventory.TotalReserved;
+            }
+            else
+            {
+                newAllocation = request.Allocation;
+                newReservation = 0;
+            }
+
+            var inventory = context.Inventories.Add(new Entities.ProductInventory
+            {
+                CreatedAt = DateTime.UtcNow,
+                ProductId = request.ProductId,
+                ProductPriceId = request.ProductPriceId,
+                Status = InventoryStatuses.Adjustment,
+                TotalAllocated = newAllocation,
+                TotalReserved = newReservation,
+            });
+
+            return await context.SaveChangesAsync(cancellationToken) > 0
+                ? Result.Ok(inventory.Entity.Id)
+                : Result.Fail<long>("Failed to create inventory entry");
+        }
+        catch (Exception ex)
+        {
+            return Result.Fail<long>(new Error(ex.Message).CausedBy(ex));
+        }
+    }
+
     public async ValueTask<Result> AddProductCategoryAsync(long productId, long categoryId, CancellationToken cancellationToken = default)
     {
         try
@@ -153,9 +271,7 @@ public sealed class ProductService(IDbContextFactory<MidrandBooksDbContext> cont
         {
             await using var context = await contextFactory.CreateDbContextAsync(cancellationToken);
 
-            var query = context.Products
-                .Include(i => i.Price)
-                .AsQueryable();
+            var query = context.Products.AsQueryable();
 
             var cultureInfo = CultureInfo.InvariantCulture;
 
@@ -306,8 +422,7 @@ public sealed class ProductService(IDbContextFactory<MidrandBooksDbContext> cont
         {
             await using var context = await contextFactory.CreateDbContextAsync(cancellationToken);
 
-            var product = await context.Products
-                .Include(i => i.Price)
+            var product = await context.Products                
                 .AsNoTracking().FirstOrDefaultAsync(p => p.Id == productId, cancellationToken);
 
             return product is null

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/Leads/LeadService.cs

@@ -1,9 +1,8 @@
-using LiteCharms.Features.Extensions;
+using LiteCharms.Features.Hasher;
 using LiteCharms.Features.Models;
 using LiteCharms.Features.TechShop.Extensions;
 using LiteCharms.Features.TechShop.Leads.Models;
 using LiteCharms.Features.TechShop.Postgres;
-using static LiteCharms.Features.Extensions.Hash;
 
 namespace LiteCharms.Features.TechShop.Leads;
 
@@ -29,7 +28,7 @@ public class LeadService(IDbContextFactory<ShopDbContext> contextFactory)
                 FeedItemId = request.FeedItemId,
                 Status = LeadStatus.New,
                 TargetId = request.TargetId,
-                AttributionHash = StringToSha256Hash.Invoke($"{request.ClickId}{request.AppClickId}{request.WebClickId}")
+                AttributionHash = HashService.StringToSha256Hash($"{request.ClickId}{request.AppClickId}{request.WebClickId}")
             });
 
             return await context.SaveChangesAsync(cancellationToken) > 0

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="MimeKit" Version="4.16.0" />
+    <PackageReference Include="MailKit" Version="4.17.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.S3" Version="4.0.23.4" />
+    <PackageReference Include="AWSSDK.Extensions.NetCore.Setup" Version="4.0.4.3" />
+    <PackageReference Include="AWSSDK.S3" Version="4.0.24" />
     <ProjectReference Include="..\LiteCharms.Features\LiteCharms.Features.csproj" />
 
     <!-- global Usings -->

LiteCharms.Features.Tests/Fixture.cs

@@ -26,6 +26,7 @@ public class Fixture : IDisposable
             .AddGarageS3(Configuration)
             .AddEmailServices(Configuration)
             .AddSingleton(Configuration)
+            .AddHashServices(Configuration)
             .BuildServiceProvider();
 
         Mediator = Services.GetRequiredService<IMediator>();

LiteCharms.Features.Tests/HashServiceFeatureTests.cs

@@ -0,0 +1,130 @@
+using LiteCharms.Features.Hasher;
+
+namespace LiteCharms.Features.Tests;
+
+public class HashServiceFeatureTests(Fixture fixture) : IClassFixture<Fixture>
+{
+    private readonly HashService hashService = fixture.Services.GetRequiredService<HashService>();
+
+    [Fact]
+    public void StringToSha256Hash_Should_GenerateHash()
+    {
+        var input = "We are the best";
+        var expectedHash = "96E17275B53F6BEB7A0D1C4F789F226D3C71CBE398585F25B3028F2B432E78AB";
+
+        var result = HashService.StringToSha256Hash(input);
+
+        Assert.NotNull(result);
+        Assert.True(HashService.IsSha256Hash(result));
+        Assert.Equal(expectedHash, result);
+    }
+
+    [Fact]
+    public void StreamToSha256Hash_Should_GenerateHash()
+    {
+        var input = "We are successful";
+        using var stream = new MemoryStream(Encoding.UTF8.GetBytes(input));
+        var expectedHash = "C27872EE494B09D72203C98FC858268F3CD3492D62AA7B766A873520C2C73AFB";
+
+        var result = HashService.StreamToSha256Hash(stream);
+
+        Assert.NotNull(result);
+        Assert.True(HashService.IsSha256Hash(result));
+        Assert.Equal(expectedHash, result);
+    }
+
+    [Fact]
+    public void BytesToSha256Hash_Should_GenerateHash()
+    {
+        var inputBytes = Encoding.UTF8.GetBytes("We are wealthy");
+        var expectedHash = "3876BF98F6E4A8E42B22C40415687D6FF13F0E887F3F508B71852298FC665737";
+
+        var result = HashService.BytesToSha256Hash(inputBytes);
+
+        Assert.NotNull(result);
+        Assert.True(HashService.IsSha256Hash(result));
+        Assert.Equal(expectedHash, result);
+    }
+
+    [Fact]
+    public void ToMd5Hash_Should_GenerateHash()
+    {
+        var input = "We manifest our desired destiny";
+        var expectedMd5Lowercase = "6c7816869bcebe4634f7afe9c66dfa08";
+
+        var result = HashService.ToMd5Hash(input);
+
+        Assert.True(result.IsSuccess);
+        Assert.True(HashService.IsMd5Hash(result.Value));
+        Assert.Equal(expectedMd5Lowercase, result.Value);
+    }
+
+    [Fact]
+    public void HashEncodeHex_Should_GenerateHash()
+    {
+        var validHexInput = "DEADBEEF42";
+
+        var result = hashService.HashEncodeHex(validHexInput);
+
+        Assert.True(result.IsSuccess);
+        Assert.False(string.IsNullOrWhiteSpace(result.Value));
+    }
+
+    [Fact]
+    public void HashEncodeIntId_Should_GenerateHash()
+    {
+        int targetId = 42;
+
+        var result = hashService.HashEncodeIntId(targetId);
+
+        Assert.True(result.IsSuccess);
+        Assert.True(result.Value.Length >= 10);
+    }
+
+    [Fact]
+    public void HashEncodeLongId_Should_GenerateHash()
+    {
+        long targetId = 9904185012L;
+
+        var result = hashService.HashEncodeLongId(targetId);
+
+        Assert.True(result.IsSuccess);
+        Assert.True(result.Value.Length >= 10);
+    }
+
+    [Fact]
+    public void DecodeIntIdHash_Should_GenerateHash()
+    {
+        int originalId = 88041;
+        var hashedString = hashService.HashEncodeIntId(originalId).Value;
+
+        var result = hashService.DecodeIntIdHash(hashedString);
+
+        Assert.True(result.IsSuccess);
+        Assert.Equal(originalId, result.Value);
+    }
+
+    [Fact]
+    public void DecodeLongIdHash_Should_GenerateHash()
+    {
+        long originalId = 9081230491823L;
+        var hashedString = hashService.HashEncodeLongId(originalId).Value;
+
+        var result = hashService.DecodeLongIdHash(hashedString);
+
+        Assert.True(result.IsSuccess);
+        Assert.Equal(originalId, result.Value);
+    }
+
+    [Fact]
+    public void DecodeHexHash_Should_GenerateHash()
+    {
+        var originalHex = "ABCDEF12345";
+        var hashedString = hashService.HashEncodeHex(originalHex).Value;
+
+        var result = hashService.DecodeHexHash(hashedString);
+
+        Assert.True(result.IsSuccess);
+        Assert.Equal(originalHex, result.Value);
+    }
+}

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>
@@ -27,6 +27,8 @@
 
   <!-- Global Usings -->
   <ItemGroup>
+    <Using Include="System.Net" />
+    <Using Include="System.Text" />
     <Using Include="Mediator" />
     <Using Include="Xunit.Abstractions" />
     <Using Include="Microsoft.Extensions.DependencyInjection" />

LiteCharms.Features.Tests/http/litecharms/app.http

@@ -0,0 +1,6 @@
+### Authentik Token Request (Service Account Explicit)
+POST {{authority}}/connect/token
+Content-Type: application/x-www-form-urlencoded
+Accept-Encoding: identity
+
+grant_type={{grantType}}&client_id={{clientId}}&client_secret={{clientSecret}}&scope={{scope}}

LiteCharms.Features.Tests/http/litecharms/http-client.env.json

@@ -0,0 +1,9 @@
+{
+  "uat": {
+    "authority": "https://sts.security.khongisa.co.za",
+    "grantType": "client_credentials",
+    "clientId": "midrandbooks-api-uat",
+    "clientSecret": "secret_5a36d0024980544c875447a4b052938becc3fbbb10b8b2c097310c1a53ba3c0a",
+    "scope": "midrandbooks-api"
+  }
+}

LiteCharms.Features.Tests/http/midrandshop-api/app.http

@@ -0,0 +1,8 @@
+## Payfast Payment Confirmation
+# This endpoint is used by Payfast to confirm the payment status of a transaction. 
+# It receives a POST request with the payment details and updates the order status accordingly.
+
+POST {{baseUrl}}/v1/payments/payfast/confirm
+Content-Type: application/x-www-form-urlencoded
+
+amount={{amount}}&item_name={{item_name}}&m_payment_id={{paymentId}}&signature={{signature}}

LiteCharms.Features/Abstractions/IEndpoint.cs

@@ -0,0 +1,6 @@
+namespace LiteCharms.Features.Abstractions;
+
+public interface IEndpoint
+{
+    void Map(IEndpointRouteBuilder builder);
+}

LiteCharms.Features/Abstractions/IJobOrchestrator.cs

@@ -0,0 +1,12 @@
+namespace LiteCharms.Features.Abstractions;
+
+public interface IJobOrchestrator
+{
+    ValueTask SendAsync<TNotification>(TNotification notification, CancellationToken cancellationToken = default)
+        where TNotification : IEvent;
+
+    ValueTask ScheduleAsync<TNotification>(TNotification notification, string cronExpression, CancellationToken cancellationToken = default) 
+        where TNotification : IEvent;
+
+    ValueTask<bool> InterruptAsync(string eventName, string? correlationId = null, CancellationToken cancellationToken = default);
+}

LiteCharms.Features/Abstractions/IService.cs

@@ -0,0 +1,3 @@
+namespace LiteCharms.Features.Abstractions;
+
+public interface IService;

LiteCharms.Features/Api/ApiVersionTargetAttribute.cs

@@ -0,0 +1,7 @@
+namespace LiteCharms.Features.Api;
+
+[AttributeUsage(AttributeTargets.Class, AllowMultiple = true)]
+public sealed class ApiVersionTargetAttribute(int majorVersion) : Attribute
+{
+    public int MajorVersion { get; } = majorVersion;
+}

LiteCharms.Features/Api/Configuration/LiteCharmsSettings.cs

@@ -0,0 +1,16 @@
+namespace LiteCharms.Features.Api.Configuration;
+
+public sealed class LiteCharmsSettings
+{
+    public string? Authority { get; set; }
+
+    public string? ClientId { get; set; }
+
+    public string? ClientSecret { get; set; }
+
+    public string? Audience { get; set; }
+
+    public string? RequiredClaimName { get; set; }
+
+    public string? RequiredClaimNameValue { get; set; }
+}

LiteCharms.Features/Api/OpenApiBearerSecuritySchemeTransformer.cs

@@ -0,0 +1,16 @@
+namespace LiteCharms.Features.Api;
+
+public sealed class OpenApiBearerSecuritySchemeTransformer : IOpenApiDocumentTransformer
+{
+    public async Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransformerContext context, CancellationToken cancellationToken)
+    {
+        var bearerScheme = new OpenApiSecurityScheme
+        {
+            Type = SecuritySchemeType.Http,
+            Scheme = "bearer",
+            Description = "JWT Authorization header using the Bearer scheme",
+        };
+
+        document.AddComponent("Bearer", bearerScheme);
+    }
+}

LiteCharms.Features/Email/Models/EmailEnquiryModel.cs

@@ -7,25 +7,25 @@ public sealed class EmailEnquiryModel
     [Required]
     [MinLength(2)]
     [MaxLength(255)]
-    [Display(Name = "Full Name")]
+    [System.ComponentModel.DataAnnotations.Display(Name = "Full Name")]
     public string? FullName { get; set; }
 
     [Required]
     [EmailAddress]
     [MinLength(5)]
     [MaxLength(255)]
-    [Display(Name = "Email Address")]
+    [System.ComponentModel.DataAnnotations.Display(Name = "Email Address")]
     public string? EmailAddress { get; set; }
 
     [Required]
     [MinLength(2)]
     [MaxLength(255)]
-    [Display(Name = "Subject")]
+    [System.ComponentModel.DataAnnotations.Display(Name = "Subject")]
     public string? EmailSubject { get; set; }
 
     [Required]
     [MinLength(2)]
     [MaxLength(2000)]
-    [Display(Name = "Message")]
+    [System.ComponentModel.DataAnnotations.Display(Name = "Message")]
     public string? Message { get; set; }
 }

LiteCharms.Features/Enums.cs

@@ -1,5 +1,36 @@
 namespace LiteCharms.Features;
 
+public enum InventoryStatuses : int
+{
+    Adjustment = 0,
+    Reserved = 1,
+    Released = 2,
+    Sold = 3,
+    Replenished = 4,
+    Correction = 5,
+}
+
+public enum LedgerStatuses : int
+{
+    Changed = 0,
+    Sent = 1,
+    Received = 2,
+    Refunded = 3,
+    Cancelled = 4,
+    Failed = 5,
+    Partial = 6,
+    Completed = 7,
+}
+
+public enum PaymentStatuses : int
+{
+    NotPaid = 0,
+    Paid = 1,
+    Cancelled = 2,
+    Requested = 3,
+    Failed = 4,
+}
+
 public enum ShippingProviderTypes : int
 {
     Dsv = 0,
@@ -114,4 +145,65 @@ public enum Priorities : int
     Low = 0,
     Medium = 1,
     High = 2,
+}
+
+public enum PublisherTypes : int
+{
+    Individual = 0,
+    Company = 1,
+    Organization = 2,
+    SelfPublished = 3,
+    UniversityPress = 4,
+    GovernmentAgency = 5,
+    NonProfit = 6,
+    Independent = 7
+}
+
+public enum BookTypes : int
+{
+    Fiction = 0,
+    NonFiction = 1,
+    Academic = 2,
+    SelfHelp = 3,
+    Biography = 4,
+    Poetry = 5,
+    Children = 6,
+    YoungAdult = 7,
+    ScienceFiction = 8,
+    Fantasy = 9
+}
+
+public enum BookContentTypes : int
+{
+    Text = 0,
+    Image = 1,
+    Video = 2,
+    Audio = 3,
+    Interactive = 4,
+    Markdown = 5,
+    Html = 6,
+    Json = 7,
+    Yaml = 8
+}
+
+public enum BookPageTypes : int
+{
+    Cover = 0,
+    Preface = 1,
+    Introduction = 2,
+    Content = 3,
+    Closing = 4,
+    Referencer = 5,
+    Credits = 6,
+    BackCover = 7
+}
+
+public enum ProductTypes : int
+{
+    Book = 1,
+    Journal = 2,
+    Magazine = 3,
+    EBook = 4,
+    Audiobook = 5,
+    Accessory = 6
 }

LiteCharms.Features/Extensions/Api.cs

@@ -0,0 +1,203 @@
+using LiteCharms.Features.Abstractions;
+using LiteCharms.Features.Api;
+using LiteCharms.Features.Api.Configuration;
+using Microsoft.AspNetCore.Authentication.JwtBearer;
+
+namespace LiteCharms.Features.Extensions;
+
+public static class Api
+{
+    public const string Books = nameof(Books);
+    public const string Payments = nameof(Payments);
+
+    public static IServiceCollection AddLiteCharmsUiSecurity(this IServiceCollection services, IConfiguration configuration)
+    {
+        var configSection = configuration.GetSection(nameof(LiteCharmsSettings));
+
+        var authOptions = new LiteCharmsSettings();
+        configSection.Bind(authOptions);
+
+        services.Configure<LiteCharmsSettings>(configSection);
+
+        services.AddAuthentication(options =>
+        {
+            options.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
+            options.DefaultChallengeScheme = OpenIdConnectDefaults.AuthenticationScheme;
+        })
+        .AddCookie(CookieAuthenticationDefaults.AuthenticationScheme)
+        .AddOpenIdConnect(OpenIdConnectDefaults.AuthenticationScheme, options =>
+        {
+            options.Authority = authOptions.Authority;           
+
+            options.ClientId = authOptions.ClientId;
+            options.ClientSecret = authOptions.ClientSecret;
+            options.SignedOutCallbackPath = "/signout-callback-oidc";
+
+            options.ResponseType = "code";
+            options.SaveTokens = true;
+            options.GetClaimsFromUserInfoEndpoint = true;
+
+            options.Scope.Clear();
+            options.Scope.Add("openid");
+            options.Scope.Add("profile");
+            options.Scope.Add("email");
+
+            options.CorrelationCookie.SecurePolicy = CookieSecurePolicy.Always;
+            options.CorrelationCookie.SameSite = SameSiteMode.None;
+            options.CorrelationCookie.HttpOnly = true;
+
+            options.NonceCookie.SecurePolicy = CookieSecurePolicy.Always;
+            options.NonceCookie.SameSite = SameSiteMode.None;
+            options.NonceCookie.HttpOnly = true;
+        });
+
+        return services;
+    }
+
+    public static IServiceCollection AddLiteCharmsApiSecurity(this IServiceCollection services, IConfiguration configuration)
+    {
+        var configSection = configuration.GetSection(nameof(LiteCharmsSettings));
+
+        var authOptions = new LiteCharmsSettings();
+        configSection.Bind(authOptions);
+
+        services.Configure<LiteCharmsSettings>(configSection);
+
+        services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
+            .AddJwtBearer(options =>
+            {
+                options.Authority = authOptions.Authority;
+                options.Audience = authOptions.Audience;
+                options.TokenValidationParameters = new TokenValidationParameters
+                {
+                    ValidIssuer = authOptions.Authority,
+                    ValidateAudience = true,
+                    ValidateIssuer = true,
+                };
+            });
+
+        if (!string.IsNullOrWhiteSpace(authOptions.RequiredClaimName) && !string.IsNullOrWhiteSpace(authOptions.RequiredClaimNameValue))
+        {
+            services.AddAuthorizationBuilder()
+                .AddPolicy("RequiredScope", policy =>
+                    policy.RequireClaim(authOptions.RequiredClaimName, authOptions.RequiredClaimNameValue));
+        }
+        else
+            services.AddAuthorization();
+
+        return services;
+    }
+
+    public static WebApplication AddSecurityEndpoints(this WebApplication app)
+    {
+        app.MapGet("/login", async (HttpContext context, string redirectUri = "/") =>
+        {
+            await context.ChallengeAsync(OpenIdConnectDefaults.AuthenticationScheme, new AuthenticationProperties
+            {
+                RedirectUri = redirectUri,                
+            });
+        });
+
+        app.MapGet("/logout", async (HttpContext context, IHttpClientFactory httpClientFactory, IOptions<LiteCharmsSettings> settings) =>
+        {
+            await context.SignOutAsync(CookieAuthenticationDefaults.AuthenticationScheme);
+
+            string currentBaseUrl = $"https://{context.Request.Host}{context.Request.PathBase}/";
+
+            await context.SignOutAsync(OpenIdConnectDefaults.AuthenticationScheme, new AuthenticationProperties
+            {
+                RedirectUri = currentBaseUrl
+            });
+        });
+
+        return app;
+    }
+
+    public static IServiceCollection AddApiServices(this IServiceCollection services, IConfiguration configuration)
+    {
+        services.AddHttpClient();
+
+        services.AddApiVersioning(options =>
+        {
+            options.DefaultApiVersion = new ApiVersion(1);
+            options.ReportApiVersions = true;
+            options.AssumeDefaultVersionWhenUnspecified = true;
+            options.ApiVersionReader = ApiVersionReader.Combine(new UrlSegmentApiVersionReader(),
+                new QueryStringApiVersionReader("version"),
+                new QueryStringApiVersionReader("version"),
+                new MediaTypeApiVersionReader("version"));
+        })
+        .AddApiExplorer(options =>
+        {
+            options.GroupNameFormat = "'v'VVV";
+            options.SubstituteApiVersionInUrl = true;
+        });
+
+        var urls = configuration["ASPNETCORE_URLS"] ?? configuration["Urls"];
+        var healthUrl = "http://localhost:8080/health";
+
+        if (!string.IsNullOrWhiteSpace(urls))
+        {
+            string firstUrl = urls.Split(';').FirstOrDefault(s => s.Contains("http://"))!
+                .Replace("0.0.0.0", "localhost")
+                .Replace("*", "localhost")
+                .Replace("+", "localhost");
+
+            healthUrl = $"{firstUrl.TrimEnd('/')}/health";
+        }
+
+        services.AddHealthChecksUI(setup =>
+        {
+            setup.SetNotifyUnHealthyOneTimeUntilChange();
+            setup.AddHealthCheckEndpoint("primary, heal", healthUrl);
+            setup.SetHeaderText("Midrand Books");
+        })
+        .AddInMemoryStorage();
+
+        services.AddOutputCache(options =>
+        {
+            options.AddBasePolicy(builder => builder.Cache());
+            options.DefaultExpirationTimeSpan = TimeSpan.FromSeconds(10);
+        });
+
+        services.AddOpenApi(options => options.AddDocumentTransformer<OpenApiBearerSecuritySchemeTransformer>());
+
+        return services;
+    }
+
+    public static IApplicationBuilder MapEndpoints(this WebApplication app, IDictionary<int, RouteGroupBuilder> versionGroups)
+    {
+        var endpoints = app.Services.GetRequiredService<IEnumerable<IEndpoint>>();
+
+        foreach (var endpoint in endpoints)
+        {
+            var versionAttributes = endpoint.GetType().GetCustomAttributes<ApiVersionTargetAttribute>().ToList();
+
+            if (versionAttributes.Count != 0)
+            {
+                foreach (var attr in versionAttributes)
+                    if (versionGroups.TryGetValue(attr.MajorVersion, out var targetGroup))
+                        endpoint.Map(targetGroup);
+            }
+            else
+                endpoint.Map(app);
+        }
+
+        return app;
+    }
+
+    public static IServiceCollection AddEndpoints(this IServiceCollection services, Assembly assembly)
+    {
+        ServiceDescriptor[] discriptors = [.. assembly.DefinedTypes
+            .Where(t => t is { IsInterface: false, IsAbstract: false })
+            .Where(t => t.IsAssignableTo(typeof(IEndpoint)))
+            .Select(t => ServiceDescriptor.Transient(typeof(IEndpoint), t))];
+
+        services.TryAddEnumerable(discriptors);
+
+        return services;
+    }
+
+    public static string ToEndpointName(this Type target, string? annotation = "") =>
+        $"{target.Name.Replace("Endpoint", string.Empty)}{annotation}".ToLower(CultureInfo.CurrentCulture);
+}

LiteCharms.Features/Extensions/Hash.cs

@@ -1,13 +1,23 @@
-namespace LiteCharms.Features.Extensions;
+using LiteCharms.Features.Hasher;
+using LiteCharms.Features.Hasher.Configuration;
+
+namespace LiteCharms.Features.Extensions;
 
 public static class Hash
 {
-    public static readonly Func<string?, string?> StringToSha256Hash = (input) => 
-        Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(input!)));
+    public const string HasherConfigSectionName = "HasherSettings";
 
-    public static readonly Func<Stream, string?> StreamToSha256Hash = (stream) =>
-        Convert.ToHexString(SHA256.HashData(stream));
+    public static IServiceCollection AddHashServices(this IServiceCollection services, IConfiguration configuration)
+    {
+        services.Configure<HasherSettings>(configuration.GetSection(HasherConfigSectionName));
 
-    public static readonly Func<byte[], string?> BytesToSha256Hash = (bytes) =>
-        Convert.ToHexString(SHA256.HashData(bytes));
-}
+        var settings = configuration.GetSection(HasherConfigSectionName).Get<HasherSettings>();
+
+        services.AddSingleton<IHashids>(_ =>
+            new Hashids(settings!.Salt, minHashLength: settings.MinHashLength));
+
+        services.AddSingleton<HashService>();
+
+        return services;
+    }    
+}

LiteCharms.Features/Extensions/Quartz.cs

@@ -1,5 +1,5 @@
-using LiteCharms.Features.Quartz;
-using LiteCharms.Features.Quartz.Abstractions;
+using LiteCharms.Features.Abstractions;
+using LiteCharms.Features.Quartz;
 using static LiteCharms.Features.Extensions.Postgres;
 
 namespace LiteCharms.Features.Extensions;

LiteCharms.Features/Hasher/Configuration/HasherSettings.cs

@@ -0,0 +1,10 @@
+namespace LiteCharms.Features.Hasher.Configuration;
+
+public sealed class HasherSettings
+{
+    public string? Salt { get; set; }
+
+    public int MinHashLength { get; set; }
+
+    public string? PayfastPassphrase { get; set; }
+}

LiteCharms.Features/Hasher/HashService.cs

@@ -0,0 +1,89 @@
+using LiteCharms.Features.Abstractions;
+
+namespace LiteCharms.Features.Hasher;
+
+public sealed partial class HashService(IHashids hasher) : IService
+{
+    [GeneratedRegex(@"\A\b[0-9a-fA-F]+\b\Z", RegexOptions.None, matchTimeoutMilliseconds: 100)]
+    private static partial Regex HexHashRegex { get; }
+
+    [GeneratedRegex(@"\A[0-9a-fA-F]{32}\Z", RegexOptions.None, matchTimeoutMilliseconds: 100)]
+    private static partial Regex Md5Regex { get; }
+
+    [GeneratedRegex(@"\A[0-9a-fA-F]{64}\Z", RegexOptions.None, matchTimeoutMilliseconds: 100)]
+    private static partial Regex Sha256Regex { get; }
+
+    public static bool IsMd5Hash(string? value) =>
+        !string.IsNullOrWhiteSpace(value) && Md5Regex.IsMatch(value);
+
+    public static bool IsSha256Hash(string? value) =>
+        !string.IsNullOrWhiteSpace(value) && Sha256Regex.IsMatch(value);
+
+    public static string? StringToSha256Hash(string? input) =>
+        string.IsNullOrEmpty(input) ? null : Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(input)));
+
+    public static string? StreamToSha256Hash(Stream stream) =>
+        stream is null ? null : Convert.ToHexString(SHA256.HashData(stream));
+
+    public static string? BytesToSha256Hash(byte[] bytes) =>
+        bytes is null ? null : Convert.ToHexString(SHA256.HashData(bytes));
+
+    public static Result<string> ToMd5Hash(string input)
+    {
+        if (string.IsNullOrEmpty(input))
+            return Result.Fail<string>("Input content cannot be null or empty for MD5 processing.");
+
+        byte[] bytes = MD5.HashData(Encoding.UTF8.GetBytes(input));
+        return Result.Ok(Convert.ToHexString(bytes).ToLowerInvariant());
+    }
+
+    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));
+
+    public Result<string> HashEncodeIntId(int id) => id < 0
+        ? Result.Fail<string>("Id cannot be negative.")
+        : Result.Ok(hasher.Encode(id));
+
+    public Result<string> HashEncodeLongId(long id) => id < 0
+        ? Result.Fail<string>("Id cannot be negative.")
+        : Result.Ok(hasher.EncodeLong(id));
+
+    public Result<int> DecodeIntIdHash(string hash)
+    {
+        if (string.IsNullOrWhiteSpace(hash)) return Result.Fail<int>("Invalid token layout.");
+
+        int[] decoded = hasher.Decode(hash);
+
+        return decoded.Length == 1 ? Result.Ok(decoded[0]) : Result.Fail<int>("Invalid or modified Int hash token.");
+    }
+
+    public Result<long> DecodeLongIdHash(string hash)
+    {
+        if (string.IsNullOrWhiteSpace(hash)) return Result.Fail<long>("Invalid token layout.");
+
+        long[] decoded = hasher.DecodeLong(hash);
+
+        return decoded.Length == 1 ? Result.Ok(decoded[0]) : Result.Fail<long>("Invalid or modified Long hash token.");
+    }
+
+    public Result<string> DecodeHexHash(string hex)
+    {
+        try
+        {
+            string decoded = hasher.DecodeHex(hex);
+
+            return string.IsNullOrEmpty(decoded)
+                ? Result.Fail<string>("Invalid or corrupted hex hash.")
+                : Result.Ok(decoded);
+        }
+        catch (FormatException fex)
+        {
+            return Result.Fail<string>(new Error("Invalid hash structure.").CausedBy(fex));
+        }
+        catch (Exception ex)
+        {
+            return Result.Fail<string>(new Error(ex.Message).CausedBy(ex));
+        }
+    }
+}

LiteCharms.Features/LiteCharms.Features.csproj

@@ -29,9 +29,45 @@
     <None Include="..\icon.png" Pack="true" PackagePath="\" />
   </ItemGroup>
 
+  <!-- Security (IODC)-->
+  <ItemGroup>
+    <PackageReference Include="IdentityModel.AspNetCore" Version="4.3.0" />
+    <PackageReference Include="IdentityModel.AspNetCore.OAuth2introspection" Version="6.2.0" />
+    <PackageReference Include="IdentityServer4.AccessTokenValidation" Version="3.0.1" />
+    <PackageReference Include="IdentityModel" Version="6.2.0" />
+    <PackageReference Include="Microsoft.AspNetCore.Authentication.Certificate" Version="10.0.8" />
+    <PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="10.0.8" />
+
+    <Using Include="Microsoft.AspNetCore.Authentication"/>
+    <Using Include="Microsoft.AspNetCore.Authentication.OpenIdConnect"/>
+    <Using Include="Microsoft.AspNetCore.Authentication.Cookies"/>
+    <Using Include="IdentityModel.AspNetCore.OAuth2Introspection"/>
+  </ItemGroup>
+
+  <!-- API Versioning -->
+  <ItemGroup>
+    <PackageReference Include="AccessTokenClient.Extensions" Version="5.1.0" />
+    <PackageReference Include="Asp.Versioning.Abstractions" Version="10.0.0" />
+    <PackageReference Include="Asp.Versioning.Http" Version="10.0.0" />
+    <PackageReference Include="Asp.Versioning.Mvc.ApiExplorer" Version="10.0.0" />
+
+    <Using Include="Asp.Versioning" />
+  </ItemGroup>
+
+  <!-- API Documentation -->
+  <ItemGroup>
+    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.8" />
+    <PackageReference Include="Scalar.AspNetCore" Version="2.14.14" />
+
+    <Using Include="Scalar.AspNetCore" />
+    <Using Include="Microsoft.OpenApi" />
+    <Using Include="Microsoft.AspNetCore.OpenApi" />
+  </ItemGroup>
+
   <!-- Quartz Scheduler-->
   <ItemGroup>    
-    <PackageReference Include="Meziantou.Analyzer" Version="3.0.96">
+    <PackageReference Include="Hashids.net" Version="1.7.0" />    
+    <PackageReference Include="Meziantou.Analyzer" Version="3.0.98">
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>    
@@ -104,7 +140,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" />
@@ -115,8 +151,8 @@
   
   <!-- Email -->
   <ItemGroup>
-    <PackageReference Include="MailKit" Version="4.16.0" />
-    <PackageReference Include="MimeKit" Version="4.16.0" />
+    <PackageReference Include="MailKit" Version="4.17.0" />
+    <PackageReference Include="MimeKit" Version="4.17.0" />
     
     <!-- Global Usings-->
     <Using Include="MimeKit" />
@@ -135,8 +171,8 @@
   
   <!-- Amazon S3 SDK -->
   <ItemGroup>
-    <PackageReference Include="AWSSDK.Extensions.NetCore.Setup" Version="4.0.4.1" />
-    <PackageReference Include="AWSSDK.S3" Version="4.0.23.4" />
+    <PackageReference Include="AWSSDK.Extensions.NetCore.Setup" Version="4.0.4.3" />
+    <PackageReference Include="AWSSDK.S3" Version="4.0.24" />
     
     <!-- global Usings -->
     <Using Include="Amazon.S3" />
@@ -146,6 +182,15 @@
 
   <!-- Shared Usings -->
   <ItemGroup>
+    <Using Include="System.Reflection" />
+    <Using Include="Microsoft.Extensions.DependencyInjection.Extensions" />
+    <Using Include="Microsoft.AspNetCore.Routing" />
+    <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" />
     <Using Include="System.Globalization" />
     <Using Include="Microsoft.AspNetCore.Builder" />
     <Using Include="Microsoft.Extensions.Hosting" />

LiteCharms.Features/Quartz/Abstractions/IJobOrchestrator.cs

@@ -1,12 +0,0 @@
-using LiteCharms.Features.Abstractions;
-
-namespace LiteCharms.Features.Quartz.Abstractions;
-
-public interface IJobOrchestrator
-{
-    Task SendAsync<TNotification>(TNotification notification, CancellationToken cancellationToken = default)
-        where TNotification : IEvent;
-
-    Task ScheduleAsync<TNotification>(TNotification notification, string cronExpression, CancellationToken cancellationToken = default) 
-        where TNotification : IEvent;
-}

LiteCharms.Features/Quartz/JobOrchestrator.cs

@@ -1,11 +1,10 @@
 using LiteCharms.Features.Abstractions;
-using LiteCharms.Features.Quartz.Abstractions;
 
 namespace LiteCharms.Features.Quartz;
 
 public sealed class JobOrchestrator(ISchedulerFactory schedulerFactory) : IJobOrchestrator
 {
-    public async Task SendAsync<TNotification>(TNotification notification, CancellationToken cancellationToken = default)
+    public async ValueTask SendAsync<TNotification>(TNotification notification, CancellationToken cancellationToken = default)
         where TNotification : IEvent
     {
         var chainedJobGroup = "onetime-jobs";
@@ -19,6 +18,7 @@ public sealed class JobOrchestrator(ISchedulerFactory schedulerFactory) : IJobOr
             .WithDescription($"Correlation ID: {notification.CorrelationId}")
             .UsingJobData(new JobDataMap { ["Payload"] = JsonSerializer.Serialize(notification) })
             .DisallowConcurrentExecution()
+            .RequestRecovery()
             .Build();
 
         var trigger = global::Quartz.TriggerBuilder.Create()
@@ -29,7 +29,7 @@ public sealed class JobOrchestrator(ISchedulerFactory schedulerFactory) : IJobOr
         await scheduler.ScheduleJob(job, new List<ITrigger> { trigger }.AsReadOnly(), replace: true, cancellationToken);
     }
 
-    public async Task ScheduleAsync<TNotification>(TNotification notification, string cronExpression, CancellationToken cancellationToken = default)
+    public async ValueTask ScheduleAsync<TNotification>(TNotification notification, string cronExpression, CancellationToken cancellationToken = default)
         where TNotification : IEvent
     {
         var chainedJobGroup = "scheduled-jobs";
@@ -63,4 +63,25 @@ public sealed class JobOrchestrator(ISchedulerFactory schedulerFactory) : IJobOr
         else
             await scheduler.ScheduleJob(job, new List<ITrigger> { trigger }.AsReadOnly(), replace: true, cancellationToken);
     }
+
+    public async ValueTask<bool> InterruptAsync(string eventName, string? correlationId = null, CancellationToken cancellationToken = default)
+    {
+        var scheduler = await schedulerFactory.GetScheduler(cancellationToken);
+
+        var jobKeyName = string.Empty;
+        var jobGroup = string.Empty;
+
+        if (!string.IsNullOrWhiteSpace(correlationId))
+        {
+            jobKeyName = $"{eventName.ToLower(CultureInfo.InvariantCulture)}-{correlationId.ToLower(CultureInfo.InvariantCulture)}";
+            jobGroup = "onetime-jobs";
+        }
+        else
+        {
+            jobKeyName = eventName.ToLower(CultureInfo.InvariantCulture);
+            jobGroup = "scheduled-jobs";
+        }
+
+        return await scheduler.Interrupt(JobKey.Create(jobKeyName, jobGroup), cancellationToken);
+    }
 }

LiteCharms.Features/Quartz/MediatorJob.cs

@@ -8,6 +8,9 @@ public sealed class MediatorJob<TNotification>(IMediator mediator) : IJob where
 {
     public async Task Execute(IJobExecutionContext context)
     {
+        if (context.Recovering)
+            Trace.WriteLine($"CRITICAL RECOVERY: Resurrecting job '{typeof(TNotification).Name}' after a previous cluster node crashed mid-execution.");
+
         var data = context.MergedJobDataMap["Payload"] as string;
 
         if (string.IsNullOrWhiteSpace(data))
@@ -21,17 +24,28 @@ public sealed class MediatorJob<TNotification>(IMediator mediator) : IJob where
 
         if (notification is null)
         {
-            Trace.WriteLine("Notification could not be JSon converted from data string, job ended");
+            Trace.WriteLine("Notification could not be Json converted from data string, job ended");
 
             return;
         }
-                
-        using var activity = MediatorTelemetry.Source.StartActivity($"Quartz: {typeof(TNotification).Name}");
-                
+
+        using var activity = MediatorTelemetry.Source.StartActivity(typeof(TNotification).Name);
+
         activity?.SetTag("event.correlation_id", notification.CorrelationId);
 
-        await mediator.Publish(notification, context.CancellationToken);
+        try
+        {
+            await mediator.Publish(notification, context.CancellationToken);
 
-        Trace.WriteLine("Job published");
+            Trace.WriteLine("Job published successfully");
+        }
+        catch (OperationCanceledException) when (context.CancellationToken.IsCancellationRequested)
+        {
+            Trace.WriteLine($"Job '{typeof(TNotification).Name}' was gracefully interrupted by the cluster control plane.");
+            
+            activity?.SetStatus(ActivityStatusCode.Ok);
+
+            return;
+        }
     }
 }

LiteCharms.Features/Quartz/RetryJobListener.cs

@@ -12,6 +12,9 @@ public sealed class RetryJobListener : IJobListener
 
     public async Task JobWasExecuted(IJobExecutionContext context, JobExecutionException? jobException, CancellationToken cancellationToken = default)
     {
+        if (context.CancellationToken.IsCancellationRequested)
+            return;
+
         if (jobException is not null && context.RefireCount < RetryCount)
             jobException.RefireImmediately = true;
     }

LiteCharms.Features/S3/Abstractions/S3ServiceBase.cs

@@ -1,4 +1,4 @@
-using static LiteCharms.Features.Extensions.Hash;
+using LiteCharms.Features.Hasher;
 
 namespace LiteCharms.Features.S3.Abstractions;
 
@@ -26,7 +26,7 @@ public abstract class S3ServiceBase(IAmazonS3 amazonS3)
 
             stream.Seek(0, SeekOrigin.Begin);
 
-            var fileHash = StreamToSha256Hash(stream);
+            var fileHash = HashService.StreamToSha256Hash(stream);
 
             if(string.IsNullOrWhiteSpace(fileHash))
                 return Result.Fail<string>("Failed to compute file hash.");
@@ -39,7 +39,7 @@ public abstract class S3ServiceBase(IAmazonS3 amazonS3)
                 Key = fileKey,
                 InputStream = stream,
                 ContentType = contentType,
-                UseChunkEncoding = false
+                UseChunkEncoding = false,
             };
 
             stream.Seek(0, SeekOrigin.Begin);