Chargily.Pay 2.0.0

<img src="https://raw.githubusercontent.com/rainxh11/chargily-pay-csharp/main/Assets/chargily_wide.svg" width="300"/>

Nuget Pacakge	Downloads
Chargily.Pay: <br/>
Chargily.Pay.AspNet:<br/>

Chargily Pay V2 .NET Client Library

A fully-featured client library to work with Chargily Pay API version 2 Online Payment Platform. The easiest and free way to integrate e-payment API through EDAHABIA of Algerie Poste and CIB of SATIM

Support with the various .NET Project-types:

Only .NET6.0 and newer versions are supported.

NOTE: Ability to receive checkout status with Webhook endpoint is only possible with project types that can host an HTTP Server.

Documentations Summary:

• Installation
• Getting Started:
  • Create a checkout without Product & Price
  • Create a Payment Link for a product
  • Create a Customer
  • Retrieve Balance Wallets
  • How to Retrieve Data:
    • Products
    • Prices
    • Customers
    • Checkouts
    • Checkout Items
    • Payment Links
    • Payment Links Items
• Usage with ASP.NET WebApi:
  • Install Chargily.Pay.AspNet Nuget Package
  • Example Usage
  • Webhook Signature Validation

Installation:

Using DotNet CLI :

dotnet add Chargily.Pay

Getting Started:

1. First create & configure a client:

    using Chargily.Pay;
    
    var chargilyClient = ChargilyPay.CreateResilientClient(config =>
                                                               {
                                                                    // toggle live mode
                                                                 config.IsLiveMode = false;
                                                                    // your chargily dev account api-secret key
                                                                 config.ApiSecretKey = "YOUR API SECRET";
                                                               });

2. Create a Product:

    var createProduct = new CreateProduct()
                            {
                              Name = "Product Name",
                              ImagesUrls = new List<Uri>()
                                           {
                                             new Uri("https://domain.com/image.png")
                                           },
                              Description = "Product Description",
                            };
    var product = await _chargilyPayClient.AddProduct(createProduct);

3. Add Price for the Product:

    var createPrice = new CreatePrice()
                          {
                            Amount = 3000,
                            Currency = Currency.DZD,
                            ProductId = product.Value.Id,
                          };
    var productPrice = await chargilyClient.AddPrice(createPrice);

4. Create a checkout:

    var checkoutItems = new List<CheckoutPriceItem>()
                            {
                              new CheckoutPriceItem()
                              {
                                Quantity = 1,
                                PriceId = productPrice.Value.Id
                              }
                            };
    var createCheckout = new Checkout(checkoutItems)
                             {
                               Description = "Checkout Description",
                               Language = LocaleType.Arabic,
                               PaymentMethod = PaymentMethod.EDAHABIA,
                               PassFeesToCustomer = true,
                               WebhookEndpointUrl = new Uri("https://domain.com/webhook/endpoint"),
                               OnFailureRedirectUrl = new Uri("https://webapp.com/checkout/fail"),
                               OnSuccessRedirectUrl = new Uri("https://webapp.com/checkout/success"),
                               CollectShippingAddress = false,
                             };
    var checkout = await chargilyClient.CreateCheckout(createCheckout);

Create a checkout without Product & Price:

    var createCheckout = new Checkout(amount: 3000, Currency.DZD)
                             {
                               Description = "Checkout Description",
                               Language = LocaleType.Arabic,
                               PaymentMethod = PaymentMethod.EDAHABIA,
                               PassFeesToCustomer = true,
                               WebhookEndpointUrl = new Uri("https://domain.com/webhook/endpoint"),
                               OnFailureRedirectUrl = new Uri("https://webapp.com/checkout/fail"),
                               OnSuccessRedirectUrl = new Uri("https://webapp.com/checkout/success"),
                               CollectShippingAddress = false,
                             };
    var fastCheckout = await chargilyClient.CreateCheckout(createCheckout);

NOTE: Checkout can be created with list of prices or using an amount + currency.

Create a Payment Link for a product:

    var createProduct = new CreateProduct()
                        {
                            /* ... */
                        };
    var product = await _chargilyPayClient.AddProduct(createProduct);
    
    var createPrice = new CreatePrice()
                      {
                            /* ... */
                      };
    var productPrice = await chargilyClient.AddPrice(createPrice);
    // above steps are similar to how to create a checkout
    var paymentLinkItems = new List<PaymentLinkPriceItem>()
                           {
                             new PaymentLinkPriceItem()
                             {
                               AdjustableQuantity = true,
                               PriceId = productPrice.Value.Id,
                               Quantity = 2
                             }
                           };
    var createPaymentLink = new CreatePaymentLink(paymentLinkItems)
                            {
                              Language = LocaleType.Arabic,
                              PassFeesToCustomer = true,
                              CollectShippingAddress = false,
                              Name = "Name",
                              CompletionMessage = "completion message",
                              IsActive = true
                            };

Create a Customer:

• Support for Customers also added in V2, and can be added to checkout also:

    var createCustomer = new CreateCustomer()
                             {
                               Name = "Customer Name",
                               Address = new CustomerAddress()
                                         {
                                           Address = "Address",
                                           Country = Country.Algeria,
                                           State = "Alger"
                                         },
                               Email = "user@email.com",
                               Phone = "+2130601010101"
                             };
    var customer = await chargilyClient.AddCustomer(createCustomer);
    
    var createCheckout = new Checkout(amount: 3000, Currency.DZD)
                             {
                               CustomerId = customer.Value.Id,
                               /* .... */
                             };
    var fastCheckout = await chargilyClient.CreateCheckout(createCheckout);

Retrieve Balance Wallets:

• Balance Wallets are refreshed automatically, to check current balance:

    foreach (var wallet in chargilyClient.Balance)
    {
     /* ... */
    }

• Configuring how often balance wallets are refreshed:

    using Chargily.Pay;
    
    var chargilyClient = ChargilyPay.CreateResilientClient(config =>
                                                               {
                                                                 /* ... */
                                                                 // refresh balance every 30 seconds 
                                                                 config.BalanceRefreshInterval = TimeSpan.FromSeconds(30);
                                                               });

• Or get balance manually:

    var balance = await chargilyClient.GetBalance();

How to Retrieve Data:

Products:

    // by id
    var byId = await chargilyClient.GetProduct("id");
    // by page number & page size
    var products = await chargilyClient.GetProducts(page: 1, pageSize: 50);
        
    // or iterate through all items using `Async Enumerable async foreach`
    await foreach(var product in chargilyClient.Products())
    {
      /* ... */
    }

Prices:

    // by id
    var byId = await chargilyClient.GetPrice("id");
    // by page number & page size
    var prices = await chargilyClient.GetPrices(page: 1, pageSize: 50);
    
    // or iterate through all items using `IAsyncEnumerable async foreach`
    await foreach(var price in chargilyClient.Prices())
    {
      /* ... */
    }

Customers:

    // by id
    var byId = await chargilyClient.GetCustomer("id");
    // by page number & page size
    var customers = await chargilyClient.GetCustomers(page: 1, pageSize: 50);
    
    // or iterate through all items using `IAsyncEnumerable async foreach`
    await foreach(var customer in chargilyClient.Customers())
    {
      /* ... */
    }

Checkouts:

    // by id
    var byId = await chargilyClient.GetCheckout("id");
    // by page number & page size
    var checkouts = await chargilyClient.GetCheckouts(page: 1, pageSize: 50);
    
    // or iterate through all items using `IAsyncEnumerable async foreach`
    await foreach(var checkout in chargilyClient.Checkouts())
    {
      /* ... */
    }

Checkout Items:

    var checkoutItems = await chargilyClient.GetCheckoutItems("checkoutId");

Payment Links:

    // by id
    var byId = await chargilyClient.GetPaymentLink("id");
    // by page number & page size
    var paymentLinks = await chargilyClient.GetPaymentLinks(page: 1, pageSize: 50);
    
    // or iterate through all items using `IAsyncEnumerable async foreach`
    await foreach(var paymentLink in chargilyClient.PaymentLinks())
    {
      /* ... */
    }

Payment Links Items:

    var paymentLinksItems = await chargilyClient.GetPaymentLinkItems("paymentLinkId");

Usage with ASP.NET WebApi:

Install Chargily.Pay.AspNet Nuget Package:

dotnet add Chargily.Pay.AspNet

Example Usage:

    using Chargily.Pay;
    using Chargily.Pay.AspNet;
    
    var builder = WebApplication.CreateBuilder(args);
    
    builder.Services
            // Register Chargily Pay Client
           .AddGlobalChargilyPayClient(config =>
                                       {
                                         // toggle live mode
                                         config.IsLiveMode = false;
                                         // your chargily dev account api-secret key
                                         config.ApiSecretKey = "YOUR API SECRET";
                                       })
            // Register Chargily Pay Webhook Signature Validator
           .AddChargilyPayWebhookValidationMiddleware();
    
    var app = builder.Build();
    
    // User Chargily Pay Webhook Signature Validator Middleware
    app.UseChargilyPayWebhookValidation();
    
    // Map Webhook Endpoint to `both POST & GET /api/checkout-webhook`
    app.MapChargilyPayWebhookEndpoint("/chargily/webhook", async (webhookContext) =>
                                                           {
                                                             // you can access the webhook body, http context, validation result
                                                             if (webhookContext.SignatureIsValid)
                                                             {
                                                               var body = webhookContext.Request;
                                                               /* do something with the webhook request body */
                                                             }
                                                           });
    
    app.Run();

Webhook Signature Validation

In the above example, the Chargily.Pay.AspNet provides built-in webhook signature validator middleware, you can register it with builder.Services.AddChargilyPayWebhookValidationMiddleware() then use it with app.UseChargilyPayWebhookValidation().

It will validate any POST request that have a header name: signature. You can override the header name with app.UseChargilyPayWebhookValidation("another_name").

Also built-in a minimal-webapi endpoint that can be registered with app.MapChargilyPayWebhookEndpoint(), and use it to access the webhook body without manually handling the validation.