FahdCloud.ThirdParty.PaymentIntegrations 1.0.5

FahdCloud.ThirdParty.PaymentIntegrations

A .NET C# library for integrating multiple third-party payment gateways into your application. This library provides a unified interface to interact with payment services such as Paymob, Stripe, Taps, MyFatoorah, Fawaterak, Moyasar, Kashier, and PayPal, enabling seamless payment processing, invoice detail retrieval, and connection health checks.

Table of Contents

• Features
• Supported Payment Gateways
• Installation
• Configuration
• Usage
  • Registering Services
  • Creating a Checkout URL
  • Retrieving Payment Details
  • Checking Connection Status
• Kashier Integration
• PayPal Integration
• Dependencies
• Contributing
• License

Features

• Unified Interface: Consistent methods across all supported payment gateways for creating checkout URLs, retrieving payment details, and checking API connectivity.
• Dependency Injection: Easy integration with ASP.NET Core applications using built-in service collection extensions.
• Validation and Error Handling: Input validation and null checks to ensure robust payment processing.
• Caching Support: Optimized authentication for Paymob using in-memory caching.
• Asynchronous Operations: Full support for asynchronous programming with cancellation tokens.

Supported Payment Gateways

The library supports the following payment gateways:

• Paymob: Handles payment intentions and transaction inquiries with authentication token caching.
• Stripe: Integrates with Stripe's checkout sessions for payment processing.
• Taps: Supports invoice creation and details retrieval for the Taps payment gateway.
• MyFatoorah: Provides region-specific API endpoints (e.g., Kuwait, UAE, Egypt) for flexible payment processing.
• Fawaterak: Enables invoice initialization and payment status checks.
• Moyasar: Supports invoice creation and payment status verification.
• Kashier: Facilitates payment processing with support for simple and card-based transactions.
• PayPal: Supports order creation, payment processing, and status verification using the PayPal Server SDK.

Each gateway implements the following core functionalities:

• Create a checkout URL for payment initiation.
• Retrieve payment or invoice details to check transaction status.
• Verify API connectivity with a health check.

Installation

1. Install the NuGet Package Install the FahdCloud.ThirdParty.PaymentIntegrations NuGet package in your project using one of the following methods:

   Using Package Manager Console:

   Install-Package FahdCloud.ThirdParty.PaymentIntegrations
   

   Using .NET CLI:

   dotnet add package FahdCloud.ThirdParty.PaymentIntegrations
   

2. Install Dependencies Ensure the following NuGet packages are installed in your project:

   <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="8.0.0" />
   <PackageReference Include="Microsoft.Extensions.Http" Version="8.0.0" />
   <PackageReference Include="Microsoft.Extensions.Caching.Memory" Version="8.0.0" />
   <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
   <PackageReference Include="Stripe.net" Version="45.0.0" />
   <PackageReference Include="PaypalServerSdk" Version="1.0.1" />
   

3. Build Requirements

   • .NET 8.0 or later
   • Visual Studio 2022 or compatible IDE

Configuration

1. Set Up Dependency Injection Register the payment integration services in your ASP.NET Core application by adding the following to your Program.cs or service configuration:

   using FahdCloud.ThirdParty.PaymentIntegrations.Extensions;
   
   var builder = WebApplication.CreateBuilder(args);
   
   // Register payment integration services
   builder.Services.AddPaymentIntegration();
   
   var app = builder.Build();
   

2. Configure Payment Gateway Settings Provide configuration settings for each payment gateway via dependency injection, configuration files (e.g., appsettings.json), or environment variables. Example configuration:

   {
     "PaymobSettings": {
       "ApiKey": "your-paymob-api-key",
       "SecretKey": "your-paymob-secret-key",
       "PublicKey": "your-paymob-public-key"
     },
     "StripeSettings": {
       "ApiKey": "your-stripe-api-key"
     },
     "TapsSettings": {
       "ApiKey": "your-taps-api-key"
     },
     "MyFatoorahSettings": {
       "ApiKey": "your-myfatoorah-api-key",
       "IsLiveMode": true,
       "MyFatoorahApiRegion": "KuwaitUAEJordanBahrainOman"
     },
     "FawaterakSettings": {
       "ApiKey": "your-fawaterak-api-key",
       "IsLiveMode": false
     },
     "MoyasarSettings": {
       "ApiKey": "your-moyasar-api-key"
     },
     "KashierSettings": {
       "SecretKey": "your-kashier-secret-key",
       "IsLiveMode": false,
       "MerchantId": "your-kashier-merchant-id",
       "PublicKey": "your-kashier-public-key"
     },
     "PayPalSettings": {
       "ClientId": "your-paypal-client-id",
       "ClientSecret": "your-paypal-client-secret",
       "IsLiveMode": false
     }
   }
   

   Inject these settings into your services using dependency injection.

Usage

Registering Services

Add the payment integration services to your service collection as shown in the Configuration section.

Creating a Checkout URL

Use the respective service to create a checkout URL for initiating a payment. Example for Paymob:

using FahdCloud.ThirdParty.PaymentIntegrations.Interfaces.Paymob;
using FahdCloud.ThirdParty.PaymentIntegrations.Models.Paymob.Requests;
using FahdCloud.ThirdParty.PaymentIntegrations.PaymentGatewaysSettings.Gateways.Paymob;

public class PaymentController
{
    private readonly IPaymobService _paymobService;

    public PaymentController(IPaymobService paymobService)
    {
        _paymobService = paymobService;
    }

    public async Task<string> CreatePaymobCheckout()
    {
        var request = new PaymobTransactionRequest
        {
            amount = 10000, // Amount in cents
            currency = "EGP",
            redirection_url = "https://your-redirect-url.com"
        };
        var settings = new PaymobSetting
        {
            ApiKey = "your-api-key",
            SecretKey = "your-secret-key",
            PublicKey = "your-public-key"
        };
        var response = await _paymobService.CreateCheckoutUrlAsync(request, settings);
        return response.checkOutUrl;
    }
}

Retrieving Payment Details

Retrieve payment or invoice details to check the transaction status. Example for Stripe:

using FahdCloud.ThirdParty.PaymentIntegrations.Interfaces.Stripe;
using FahdCloud.ThirdParty.PaymentIntegrations.Models.Stripe.Request;
using FahdCloud.ThirdParty.PaymentIntegrations.PaymentGatewaysSettings.Gateways.Stripe;
using Stripe.Checkout;

public class PaymentController
{
    private readonly IStripeService _stripeService;

    public PaymentController(IStripeService stripeService)
    {
        _stripeService = stripeService;
    }

    public async Task<bool> GetStripePaymentStatus(string sessionId)
    {
        var request = new StripeSessionDetailsRequest { session_id = sessionId };
        var settings = new StripeSetting { ApiKey = "your-api-key" };
        var response = await _stripeService.GetSessionDetails(request, settings);
        return response.successStatus;
    }
}

Checking Connection Status

Verify the connectivity to a payment gateway's API. Example for Taps:

using FahdCloud.ThirdParty.PaymentIntegrations.Interfaces.Taps;
using FahdCloud.ThirdParty.PaymentIntegrations.PaymentGatewaysSettings.Gateways.Taps;

public class PaymentController
{
    private readonly ITapsService _tapsService;

    public PaymentController(ITapsService tapsService)
    {
        _tapsService = tapsService;
    }

    public async Task<bool> CheckTapsConnection()
    {
        var settings = new TapsSetting { ApiKey = "your-api-key" };
        return await _tapsService.CheckConnection(settings);
    }
}

Kashier Integration

The Kashier payment gateway supports both simple and card-based payment flows. Below is an example of how to integrate Kashier for creating a checkout URL and retrieving payment details.

Configuring Kashier

Ensure the KashierSettings are properly configured in your appsettings.json or via dependency injection:

{
  "KashierSettings": {
    "SecretKey": "your-kashier-secret-key",
    "IsLiveMode": false,
    "MerchantId": "your-kashier-merchant-id",
    "PublicKey": "your-kashier-public-key"
  }
}

Creating a Kashier Checkout URL

Use the IKashierService to create a checkout URL for initiating a payment:

using FahdCloud.ThirdParty.PaymentIntegrations.Interfaces.Kashier;
using FahdCloud.ThirdParty.PaymentIntegrations.Models.Kashier.Request;
using FahdCloud.ThirdParty.PaymentIntegrations.PaymentGatewaysSettings.Gateways.Kashier;

public class PaymentController
{
    private readonly IKashierService _kashierService;

    public PaymentController(IKashierService kashierService)
    {
        _kashierService = kashierService;
    }

    public async Task<string> CreateKashierCheckout()
    {
        var request = new KashierInvoiceRequest
        {
            paymentType = "simple",
            customerName = "Customer Name",
            dueDate = DateTime.Now.AddDays(1),
            isSuspendedPayment = false,
            description = "Charge User Wallet",
            redirectUrl = "https://example.com/return",
            totalAmount = 100,
            currency = "EGP",
            state = "submitted",
            invoiceItems = new List<KashierCreateInvoiceItemDto>
            {
                new KashierCreateInvoiceItemDto
                {
                    itemName = "Wallet Top-up",
                    quantity = 1,
                    unitPrice = 100,
                    subTotal = 100,
                    description = "Wallet credit deposit"
                }
            }
        };

        var settings = new KashierSetting
        {
            SecretKey = "your-kashier-secret-key",
            IsLiveMode = false,
            MerchantId = "your-kashier-merchant-id",
            PublicKey = "your-kashier-public-key"
        };

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

Retrieving Kashier Payment Details

Retrieve payment details to verify the transaction status:

using FahdCloud.ThirdParty.PaymentIntegrations.Interfaces.Kashier;
using FahdCloud.ThirdParty.PaymentIntegrations.Models.Kashier.Request;
using FahdCloud.ThirdParty.PaymentIntegrations.PaymentGatewaysSettings.Gateways.Kashier;

public class PaymentController
{
    private readonly IKashierService _kashierService;

    public PaymentController(IKashierService kashierService)
    {
        _kashierService = kashierService;
    }

    public async Task<bool> GetKashierPaymentStatus(string merchantOrderId)
    {
        var request = new KashierInvoiceRequestDetails { merchantOrderId = merchantOrderId };
        var settings = new KashierSetting
        {
            SecretKey = "your-kashier-secret-key",
            IsLiveMode = false,
            MerchantId = "your-kashier-merchant-id",
            PublicKey = "your-kashier-public-key"
        };

        var response = await _kashierService.GetKashierInvoiceDetails(request, settings);
        return response.successStatus;
    }
}

Notes on Kashier Integration

• Payment Types: Kashier supports simple and card payment types. Choose the appropriate type based on your payment flow.
• Amount Handling: The totalAmount and unitPrice should be in the smallest currency unit (e.g., 100 for 100 EGP).
• Redirect URL: Ensure the redirectUrl is a valid endpoint in your application to handle post-payment callbacks.
• Testing: Use the IsLiveMode = false setting for sandbox testing with Kashier’s test credentials.

PayPal Integration

The PayPal payment gateway supports order creation and payment processing using the PayPal Server SDK. Below is an example of how to integrate PayPal for creating a checkout URL and retrieving payment details.

Configuring PayPal

Ensure the PayPalSettings are properly configured in your appsettings.json or via dependency injection:

{
  "PayPalSettings": {
    "ClientId": "your-paypal-client-id",
    "ClientSecret": "your-paypal-client-secret",
    "IsLiveMode": false
  }
}

Creating a PayPal Checkout URL

Use the IPayPalService to create a checkout URL for initiating a payment:

using FahdCloud.ThirdParty.PaymentIntegrations.Interfaces.Paypal;
using FahdCloud.ThirdParty.PaymentIntegrations.PaymentGatewaysSettings.Gateways.Paypal;
using PaypalServerSdk.Standard.Models;

public class PaymentController
{
    private readonly IPayPalService _payPalService;

    public PaymentController(IPayPalService payPalService)
    {
        _payPalService = payPalService;
    }

    public async Task<string> CreatePayPalCheckout()
    {
        var request = new OrderRequest
        {
            Intent = CheckoutPaymentIntent.Capture,
            PurchaseUnits = new List<PurchaseUnitRequest>
            {
                new PurchaseUnitRequest
                {
                    Amount = new AmountWithBreakdown
                    {
                        CurrencyCode = "USD",
                        MValue = "50.00",
                        Breakdown = new AmountBreakdown
                        {
                            ItemTotal = new Money
                            {
                                CurrencyCode = "USD",
                                MValue = "50.00"
                            }
                        }
                    },
                    Items = new List<Item>
                    {
                        new Item
                        {
                            Name = "Wallet Top-up",
                            Quantity = "1",
                            UnitAmount = new Money
                            {
                                CurrencyCode = "USD",
                                MValue = "50.00"
                            },
                            Description = "Wallet credit deposit"
                        }
                    }
                }
            },
            ApplicationContext = new OrderApplicationContext
            {
                ReturnUrl = "https://example.com/return",
                CancelUrl = "https://example.com/cancel",
                UserAction = OrderApplicationContextUserAction.PayNow
            }
        };

        var settings = new PayPalSetting
        {
            ClientId = "your-paypal-client-id",
            ClientSecret = "your-paypal-client-secret",
            IsLiveMode = false
        };

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

Retrieving PayPal Payment Details

Retrieve payment details to verify the transaction status:

using FahdCloud.ThirdParty.PaymentIntegrations.Interfaces.Paypal;
using FahdCloud.ThirdParty.PaymentIntegrations.Models.Shared.Request;
using FahdCloud.ThirdParty.PaymentIntegrations.PaymentGatewaysSettings.Gateways.Paypal;

public class PaymentController
{
    private readonly IPayPalService _payPalService;

    public PaymentController(IPayPalService payPalService)
    {
        _payPalService = payPalService;
    }

    public async Task<bool> GetPayPalPaymentStatus(string transactionId)
    {
        var request = new InvoiceDetailRequest { gatewayTransactionId = transactionId };
        var settings = new PayPalSetting
        {
            ClientId = "your-paypal-client-id",
            ClientSecret = "your-paypal-client-secret",
            IsLiveMode = false
        };

        var response = await _payPalService.GetSessionDetails(request, settings);
        return response.successStatus;
    }
}

Notes on PayPal Integration

• Payment Intent: The Intent is set to CAPTURE for immediate payment capture. Use AUTHORIZE for delayed capture if needed.
• Currency Support: PayPal supports multiple currencies (e.g., USD, EGP). Ensure the CurrencyCode matches your requirements.
• Redirect URLs: Provide valid ReturnUrl and CancelUrl to handle post-payment and cancellation scenarios.
• Testing: Use IsLiveMode = false for sandbox testing with PayPal’s test credentials from the PayPal Developer Dashboard.
• SDK Dependency: The PaypalServerSdk package is required for PayPal API interactions.

Dependencies

• Microsoft.Extensions.DependencyInjection: For dependency injection.
• Microsoft.Extensions.Http: For HTTP client factory.
• Microsoft.Extensions.Caching.Memory: For caching Paymob authentication tokens.
• Newtonsoft.Json: For JSON serialization/deserialization.
• Stripe.net: For Stripe API interactions.
• PaypalServerSdk: For PayPal API interactions.
• System.ComponentModel.DataAnnotations: For request validation.

Contributing

Contributions are welcome! Please submit a pull request or open an issue on the repository for bug reports, feature requests, or improvements.

License

This project is licensed under the MIT License. See the LICENSE file for details.