FahdCloud.ThirdParty.PaymentIntegrations 10.0.1

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 10+ 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": {
    "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
    }
  }
}

📖 Gateway Integration Details

1. 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

2. 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);

3. 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);

4. 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);

5. 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);

6. 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);

7. 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);

8. 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);

9. 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);

10. 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);

🧪 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.