FahdCloud.ThirdParty.PaymentIntegrations 10.0.14

FahdCloud.ThirdParty.PaymentIntegrations

A premium .NET 10.0 C# library for integrating multiple third-party payment gateways into your application with a unified, clean API. This library simplifies the complexity of interacting with various payment providers, enabling seamless payment processing, BNPL (Buy Now Pay Later) solutions, and health checks.

🚀 Key Features

• Unified Interface: Consistent patterns across all 12 supported payment gateways.
• Modern .NET Stack: Built specifically for .NET 10.0+ using IHttpClientFactory and System.Text.Json.
• BNPL Support: Native integration for popular MENA região Buy Now Pay Later providers like Tabby and Tamara.
• Dependency Injection Ready: Fluent registration with IServiceCollection.
• Safe & Robust: Comprehensive validation, error handling, and cancellation token support.
• Developer Friendly: Extensive XML documentation and a built-in CLI testing tool.

💳 Supported Payment Gateways

🛠️ Configuration & Installation

1. Install via NuGet

Install-Package FahdCloud.ThirdParty.PaymentIntegrations

2. Dependency Injection Registration

Add the following to your Program.cs:

using FahdCloud.ThirdParty.PaymentIntegrations.Extensions;

// Registers all gateway services and the Factory
builder.Services.AddPaymentIntegration();

3. App Settings Configuration

Configure your gateways in appsettings.json. Below is a comprehensive example of all settings classes:

{
  "PaymentGateways": {
    "ClickPay": {
      "ApiKey": "your_api_key_here",
      "ApiSecret": "your_api_secret_here",
      "IsLiveMode": false
    },
    "Tabby": {
      "ApiKey": "pk_test_...",
      "MerchantCode": "your_code",
      "IsLiveMode": false
    },
    "Tamara": {
      "ApiKey": "your_token",
      "ApiUrl": "https://api-sandbox.tamara.co",
      "IsLiveMode": false
    },
    "Paypal": {
      "ClientId": "your_id",
      "ClientSecret": "your_secret",
      "IsLiveMode": false
    },
    "Stripe": { "ApiKey": "sk_test_..." },
    "Paymob": {
      "ApiKey": "...",
      "SecretKey": "...",
      "PublicKey": "..."
    },
    "MyFatoorah": {
      "ApiKey": "...",
      "IsLiveMode": false,
      "MyFatoorahApiRegion": "SaudiArabia" 
    },
    "Taps": { "ApiKey": "sk_test_..." },
    "Moyasar": { "ApiKey": "sk_test_..." },
    "Fawaterak": { "ApiKey": "...", "IsLiveMode": false },
    "Kashier": {
      "MerchantId": "...",
      "PublicKey": "...",
      "SecretKey": "...",
      "IsLiveMode": false
    },
    "XPay": {
      "ApiKey": "xpay_test_...",
      "IsLiveMode": false,
      "BaseUrl": "https://api.xpay.app"
    }
  }
}

📖 Gateway Integration Details

1. ClickPay

ClickPay is a Saudi Arabian payment gateway providing simple invoice-based payment flows with sandbox and production environments.

• Interface: IClickPayService
• Settings: ClickPaySetting
• Models: ClickPayCheckoutRequest, ClickPayPaymentDetailsRequest

var request = new PaymentCheckoutRequest
{
    ReferenceId = "INV-2024-001",
    Currency = "SAR",
    Description = "Invoice payment",
    PaymentMethod = ClickPayPaymentMethodTypeConst.Mada, // Optional: specify payment method
    Customer = new PaymentCustomer
    {
        FirstName = "Ahmed",
        Email = "customer@example.com",
        PhoneNumber = "+966501234567"
    },
    Urls = new PaymentRedirectUrls
    {
        SuccessUrl = "https://yoursite.com/success",
        CallbackUrl = "https://yoursite.com/webhook"
    },
    Items = new List<PaymentLineItem>
    {
        new() 
        { 
            Name = "Product 1", 
            Description = "Premium widget",
            Sku = "SKU-001",
            Quantity = 2, 
            UnitPrice = 75m, 
            Currency = "SAR",
            ProductUrl = "https://yoursite.com/product1"
        }
    },
    TaxAmount = 15m,
    ShippingAmount = 10m,
    DiscountAmount = 5m
};

var response = await _clickPayService.CreateCheckoutUrlAsync(request, settings);
// Redirect user to: response.CheckoutUrl

// Check payment status
var statusRequest = new ClickPayPaymentDetailsRequest { TransactionId = response.GatewayTransactionId };
var status = await _clickPayService.GetPaymentDetails(statusRequest, settings);

Key Features:

• Sandbox URL: https://sandbox.clickpay.sa
• Production URL: https://secure.clickpay.sa
• Authentication: Bearer token via API key
• Health check endpoint available via CheckConnection()
• Invoice-based checkout with line items support
• Automatic calculation of taxes, shipping, and discounts

Supported Payment Methods:

Request Structure: The ClickPay integration automatically maps the unified PaymentCheckoutRequest to ClickPay's invoice format, including:

• profile_id - Your merchant profile ID (from settings)
• tran_type - Transaction type ("sale")
• tran_class - Transaction class ("ecom")
• cart_id - Your reference ID
• cart_amount - Total amount (calculated from items + tax + shipping - discount)
• invoice.line_items - Array of items with detailed breakdown
• invoice.shipping_charges - Shipping amount
• invoice.extra_charges - Tax amount
• invoice.extra_discount - Discount amount
• hide_shipping - Always true for digital payments

// Example: Using MADA payment method
var request = new PaymentCheckoutRequest
{
    ReferenceId = "INV-2024-001",
    Currency = "SAR",
    PaymentMethod = ClickPayPaymentMethodTypeConst.Mada, // Use "mada" for KSA
    Items = [ new PaymentLineItem { Name = "Item", Quantity = 1, UnitPrice = 100m } ]
};

// Example: Using STC Pay
var stcPayRequest = new PaymentCheckoutRequest
{
    ReferenceId = "INV-2024-002",
    Currency = "SAR",
    PaymentMethod = ClickPayPaymentMethodTypeConst.StcPay,
    Items = [ new PaymentLineItem { Name = "Item", Quantity = 1, UnitPrice = 100m } ]
};

// Example: Multiple payment methods allowed
var multiMethodRequest = new PaymentCheckoutRequest
{
    ReferenceId = "INV-2024-003",
    Currency = "SAR",
    PaymentMethod = ClickPayPaymentMethodTypeConst.Card, // Can specify primary method
    Items = [ new PaymentLineItem { Name = "Item", Quantity = 1, UnitPrice = 100m } ]
};

2. Tabby (BNPL)

Tabby is the leading BNPL provider in the GCC. It requires mandatory buyer data and specific currency codes (AED, SAR, etc.).

• Interface: ITabbyService
• Settings: TabbySetting
• Model: TabbyCheckoutRequest

var request = new TabbyCheckoutRequest {
    Payment = new() { Amount = 150.00m, Currency = "SAR" },
    Buyer = new() {
        Email = "customer@example.com",
        Phone = "+966501112223", // Mandatory: Include Country Code
        FirstName = "Fahd",
        LastName = "Cloud"
    },
    RedirectUrls = new() {
        Success = "https://yoursite.com/success",
        Cancel = "https://yoursite.com/cancel"
    }
};

var response = await _tabbyService.CreateCheckoutUrlAsync(request, settings);
// Redirect user to: response.CheckoutUrl

3. Tamara (BNPL)

Tamara provides installments and "Pay Now" options. It uses a region-specific base URL.

• Interface: ITamaraService
• Settings: TamaraSetting
• Model: TamaraCheckoutRequest

var request = new TamaraCheckoutRequest {
    OrderReferenceId = "INV-2024-001",
    PaymentType = TamaraPaymentTypeConst.PayByInstallments,
    OrderAmount = new() { Amount = 500.00m, Currency = "SAR" },
    Consumer = new() {
        FirstName = "Ahmed",
        LastName = "Test",
        PhoneNumber = "+966501234567"
    }
};

var response = await _tamaraService.CreateCheckoutUrlAsync(request, settings);

4. PayPal

Uses the official PayPal Server SDK for order creation and capture.

• Interface: IPayPalService
• Settings: PayPalSetting

var request = new OrderRequest {
    Intent = CheckoutPaymentIntent.Capture,
    PurchaseUnits = new List<PurchaseUnitRequest> {
        new() {
            Amount = new() { CurrencyCode = "USD", MValue = "100.00" }
        }
    }
};

var response = await _payPalService.CreateCheckoutUrlAsync(request, settings);

5. Stripe

Stripe integration uses the official Stripe.net SDK and the Checkout Session flow.

• Interface: IStripeService
• Settings: StripeSetting
• Model: SessionCreateOptions (from Stripe.net)

var options = new SessionCreateOptions {
    PaymentMethodTypes = new List<string> { "card" },
    LineItems = new List<SessionLineItemOptions> {
        new() {
            PriceData = new SessionLineItemPriceDataOptions {
                UnitAmount = 2000, // 20.00 USD
                Currency = "usd",
                ProductData = new SessionLineItemPriceDataProductDataOptions { Name = "Test Product" },
            },
            Quantity = 1,
        },
    },
    Mode = "payment",
    SuccessUrl = "https://example.com/success",
    CancelUrl = "https://example.com/cancel",
};

var response = await _stripeService.CreateCheckoutUrlAsync(options, settings);

6. Paymob

Paymob uses the unified "Intention" flow for modern checkouts.

• Interface: IPaymobService
• Settings: PaymobSetting
• Model: PaymobTransactionRequest

var request = new PaymobTransactionRequest {
    amount = 1000, // 10.00 EGP (in cents)
    currency = "EGP",
    billing_data = new() {
        first_name = "Fahd",
        last_name = "Cloud",
        email = "test@example.com",
        phone_number = "+201012345678"
    },
    items = new() { new() { name = "Item 1", amount = 1000, quantity = 1 } }
};

var response = await _paymobService.CreateCheckoutUrlAsync(request, settings);

7. MyFatoorah

Supports multiple regions in the Middle East with a single API.

• Interface: IMyFatooraService
• Settings: MyFatooraSetting
• Model: MyFatooraInvoiceRequest

var request = new MyFatooraInvoiceRequest {
    InvoiceValue = 100,
    CustomerName = "Ahmed test",
    DisplayCurrencyIso = "SAR",
    CallBackUrl = "https://example.com/callback",
    ErrorUrl = "https://example.com/error"
};

var response = await _myFatooraService.CreateCheckoutUrlAsync(request, settings);

8. Taps (Tap Payments)

A GCC-based provider supporting various local payment methods.

• Interface: ITapsService
• Settings: TapsSetting
• Model: TapsInvoiceRequest

var request = new TapsInvoiceRequest {
    amount = 50,
    currency = "KWD",
    customer = new() { first_name = "Test", email = "test@tap.company" },
    redirect = new() { url = "https://example.com/redirect" }
};

var response = await _tapsService.CreateCheckoutUrlAsync(request, settings);

9. Moyasar

A clean, card-focused gateway for the Saudi Arabian market.

• Interface: IMoyasarService
• Settings: MoyasarSetting
• Model: MoyasarInvoiceRequest

var request = new MoyasarInvoiceRequest {
    amount = 10000, // 100.00 SAR (in halalas)
    currency = "SAR",
    description = "Order #123",
    callback_url = "https://example.com/callback"
};

var response = await _moyasarService.CreateCheckoutUrlAsync(request, settings);

10. Fawaterak

Focuses on the Egyptian market with simplified invoice flows.

• Interface: IFawaterakService
• Settings: FawaterakSetting
• Model: FawaterakInvoiceRequest

var request = new FawaterakInvoiceRequest {
    cartTotal = 250,
    customer = new() { first_name = "User", last_name = "Test", email = "user@test.com" },
    cartItems = new() { new() { name = "Example", price = 250, quantity = 1 } }
};

var response = await _fawaterakService.CreateCheckoutUrlAsync(request, settings);

11. Kashier

Provides a secure hosted checkout for Egyptian merchants.

• Interface: IKashierService
• Settings: KashierSetting
• Model: KashierInvoiceRequest

var request = new KashierInvoiceRequest {
    amount = 150,
    currency = "EGP",
    customerName = "Test User",
    merchantOrderId = "ORD-456",
    redirectUrl = "https://example.com/kashier-callback"
};

var response = await _kashierService.CreateCheckoutUrlAsync(request, settings);

12. XPay

XPay provides hosted checkout sessions with support for 15 currencies (EGP, USD, EUR, GBP, SAR, AED, QAR, KWD, JOD, OMR, BHD, LYD, AUD, CAD, CNY) and multiple payment methods (card, Fawry, Aman, ValU, wallets, etc.). Uses https://api.xpay.app with GET /account health check.

• Interface: IXPayService
• Settings: XPaySetting
• Models: PaymentCheckoutRequest (canonical) → XPayCreateCheckoutSessionRequest / XPayCheckoutSessionResponse

var request = new PaymentCheckoutRequest
{
    ReferenceId = Guid.NewGuid().ToString("N"),
    Currency = "EGP",
    Description = "Order #123",
    Customer = new PaymentCustomer
    {
        FirstName = "Ahmed",
        LastName = "Test",
        Email = "test@test.com",
        PhoneNumber = "+201012345678"
    },
    Urls = new PaymentRedirectUrls
    {
        SuccessUrl = "https://example.com/success?session={CHECKOUT_SESSION_ID}",
        CancelUrl = "https://example.com/cancel"
    },
    ExpirationMinutes = 60,
    Items =
    [
        new PaymentLineItem
        {
            Name = "Wallet Top-up",
            Description = "Test item",
            Quantity = 1,
            UnitPrice = 100m, // 100 EGP -> 10000 piasters (smallest unit)
            Currency = "EGP",
            Sku = "SKU-XPAY-001"
        }
    ]
};

var settings = new XPaySetting
{
    ApiKey = "xpay_test_...",
    IsLiveMode = false,
    BaseUrl = "https://api.xpay.app"
};

var response = await _xpayService.CreateCheckoutUrlAsync(request, settings);
// Redirect user to: response.CheckoutUrl (response.Url from 201)
// Transaction ID: response.GatewayTransactionId (= session id)

// Health check (uses GET https://api.xpay.app/account)
var isConnected = await _xpayService.CheckConnection(settings);

// Verify after return
var details = await _xpayService.GetPaymentDetails(
    new XPayPaymentDetailsRequest { CheckoutSessionId = response.GatewayTransactionId! }, settings);
// Success when paymentStatus == "paid" (do not use status alone per XPay docs)
var isPaid = details.SuccessStatus;

Key Features:

• Base URL: https://api.xpay.app (configurable via XPaySetting.BaseUrl)
• Auth: Authorization: Bearer {ApiKey} (401 invalid_api_key on failure)
• Checkout: POST /checkout/sessions with afterCompletion redirect, currency, lineItems.priceData.unitAmount (smallest unit)
• Health: GET /account
• Status: status (open/complete/expired) + paymentStatus (paid/unpaid/no_payment_required) — check paymentStatus for fulfilment

Canonical Mapping (XPay afterCompletion):

• PaymentCheckoutRequest.Urls.SuccessUrl/CallbackUrl → afterCompletion: { type: "redirect", redirect: { url } }
• No URL provided → afterCompletion: { type: "hosted_confirmation" }
• PaymentLineItem.UnitPrice (major) → priceData.unitAmount (minor *100, e.g. 100 EGP → 10000)
• ExpirationMinutes → expiresAfterMinutes

🧪 Testing Environment

Clinical Testing Console

The project includes a comprehensive Console Test Application located in the Test directory. This tool allows you to manually verify integrations without setting up a web server.

How to run:

1. Navigate to Test directory.
2. Update PaymentSettingsFactory.cs with your test credentials.
3. Run dotnet run.
4. Follow the menu prompts to process payments and verify statuses.

Test Implementations Reference

For real-world examples of how to implement each gateway, refer to the files in: d:\Career\Work\Libraries\FahdCloud.ThirdParty\Test\Gateways\

Sandbox Credentials

• Stripe: Use 4242... cards. View Specs
• Tabby: Use phone numbers like +971500000001. View Docs
• Tamara: Use +966550000000 for sandbox. View Docs

📂 Implementation Details

Core Infrastructure

• Interfaces: Located in FahdCloud.ThirdParty.PaymentIntegrations\Interfaces\
• Services: Located in FahdCloud.ThirdParty.PaymentIntegrations\Services\
• Shared Models: Common response structures are in Models\Shared\.

API Standard Response

Every CreateCheckoutUrlAsync returns a CheckoutResponse<T> which includes:

• CheckoutUrl: The URL to redirect the user.
• GatewayTransactionId: The provider's internal ID.
• PaymentDetailsJson: The raw response for logging.

📝 Integration Steps Summary

1. Register: Call AddPaymentIntegration() in IServiceCollection.
2. Configure: Provision the appropriate Setting class (e.g., PaymobSetting).
3. Process: Use the specific service (e.g., IPaymobService) and call CreateCheckoutUrlAsync(request, settings).
4. Verify: Implement a callback/webhook that uses GetPaymentDetails to confirm the transaction.
5. Test: Verified using the Test project before moving to production.

📜 License

This project is licensed under the MIT License.