Welcome to the LibertePay SDK Docs

LibertePay .NET SDK provides a comprehensive and seamless payment integration solution for your .NET applications. This SDK simplifies interaction with LibertePay's robust payment processing services, offering a clean, intuitive API for all your payment needs.

✨ Features

đŸ’ģ Installation

Get started quickly by installing the LibertePay SDK via NuGet:

LibertePay.Core.Sdk

⚙ī¸ Configuration

Basic Configuration

Add the LibertePay configuration details to your appsettings.json file. Replace the placeholder values with your actual credentials provided during your LibertePay setup.

{
  "LibertePay": {
    "BaseUrl": "https://app-base-url/", /* Provided during LibertePay setup */
    "Username": "your-username", /* Provided during LibertePay setup */
    "Password": "your-password", /* Provided during LibertePay setup */
    "HttpClientTimeoutSeconds": 30,
    "CallbackUrl": "https://your-domain.com/webhook", /* Provided during LibertePay setup */
    "TelemetryApiUrl": "" /* Provided during LibertePay setup */
  }
}

Service Registration

Register the LibertePay services in your Program.cs (for .NET 6+) or Startup.cs file using the extension method:

using LibertePay.Core.DependencyInjection;
using Microsoft.Extensions.DependencyInjection; // Required for AddLibertePay

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
// ... (other service registrations)

builder.Services.AddLibertePay(builder.Configuration);

// ... (rest of your Program.cs/Startup.cs)

🛡ī¸ Error Handling

The SDK provides a consistent response format through the LibertePayResponse<T> class, simplifying error detection and handling:

🚀 Usage Guide

1. Name Enquiry Services

Bank Account Name Enquiry (Single & Bulk)

using LibertePay.Core.Clients; // For ILibertePayClient
using LibertePay.Core.Requests; // For NameEnquiryRequest, BulkNameEnquiryRequest etc.
using LibertePay.Core.Constants; // For Channels, InstitutionCodes
using Microsoft.AspNetCore.Mvc; // For IActionResult, HttpGet
using Microsoft.Extensions.Logging; // For ILogger
using System;
using System.Threading.Tasks;
using System.Collections.Generic;
using System.Linq; // For .Select()

[ApiController]
[Route("api/[controller]")]
public class PaymentServiceController : ControllerBase // Renamed for clarity as an API controller
{
    // ... implementation ...
}

Mobile Money Name Enquiry (Single & Bulk)

// Inside PaymentServiceController class

/// 
/// Verifies a single mobile money account name.
/// 
[HttpGet("VerifyMobileMoney")]
public async Task VerifyMobileMoneyAsync()
{
    // ... implementation ...
}

2. Payment Collections

Mobile Money Collection

// Inside PaymentServiceController class

/// 
/// Initiates a mobile money collection (debit) from a customer's account.
/// 
[HttpGet("MobileMoneyCollection")]
public async Task MobileMoneyCollection(decimal amount, string description)
{
    // ... implementation ...
}

3. Disbursements

Bank Disbursement

// Inside PaymentServiceController class

/// 
/// Handles a single bank disbursement (credit) to a recipient's bank account.
/// 
public async Task DisburseToBankAsync(decimal amount, string description)
{
    // ... implementation ...
}

Mobile Money Disbursement

// Inside PaymentServiceController class

/// 
/// Handles a single mobile money disbursement (credit) to a recipient's mobile money wallet.
/// 
public async Task DisburseToMobileMoneyAsync(decimal amount, string description)
{
    // ... implementation ...
}

4. Transaction Management

Check Transaction Status

using LibertePay.Core.Responses; // For TransactionStatusResponse
using LibertePay.Core.Requests; // For TransactionStatusRequest
using LibertePay.Core.Constants; // For ErrorCodes (if applicable)

// Inside PaymentServiceController or a dedicated TransactionService

/// 
/// Checks the status of a single transaction.
/// 
public async Task CheckTransactionStatusAsync(
    string transactionId,
    string transactionType)
{
    // ... implementation ...
}

5. Account Services

Check Balance

// Inside PaymentServiceController or a dedicated AccountService

/// 
/// Retrieves the available and current balance of your LibertePay account.
/// 
public async Task<(decimal Available, decimal Current)> GetBalanceAsync()
{
    // ... implementation ...
}

↩ī¸ Callback Implementation

1. Configure Callback URL

Ensure your callback URL is correctly configured in your appsettings.json. This is the endpoint LibertePay will send notifications to.

{
  "LibertePay": {
    "CallbackUrl": "https://your-domain.com/api/callback" /* This URL must be provided during LibertePay setup */
  }
}

2. Callback Types and Scenarios

3. Callback Payload Structure

Transaction Callback

{
  "status": "string",          // Human-readable status (e.g., "SUCCESS", "PENDING", "FAILED")
  "statusCode": "string",      // Numeric status code (e.g., "00" for success, "01" for pending)
  "message": "string",         // Additional details or error message
  "transactionId": "string",   // Your original transaction ID
  "institutionApprovalCode": "string", // Approval code from the institution
  "externalTransactionId": "string"    // LibertePay's internal transaction ID
}

Mandate Callback

{
  "statusCode": "string",    // Numeric status code
  "status": "string",        // Human-readable status (e.g., "ACTIVE", "CANCELLED", "EXPIRED", "FAILED")
  "message": "string",       // Additional details or error message
  "expiryDate": "string",    // Expiry date of the mandate (if applicable)
  "transactionId": "string", // Original transaction ID related to mandate creation/payment
  "mandateReference": "string", // Unique reference for the mandate
  "mandateId": "string",     // LibertePay's ID for the mandate
  "msisdnToken": null        // MSISDN token (if applicable for mobile money mandates)
}

4. Create Callback Controller

using LibertePay.Core.Callbacks; // Assuming these types are defined in your SDK
using LibertePay.Core.Clients;
using LibertePay.Core.Constants; // For ErrorCodes
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;
using System;
using System.Threading;
using System.Threading.Tasks;

[ApiController]
[Route("api/[controller]")]
public class CallbackController : ControllerBase
{
    // ... implementation ...
}

đŸĻ Institution Codes

The SDK provides a type-safe way to interact with various financial institutions through the InstitutionCodes enum. This offers several benefits:

Available Institution Codes

Mobile Money Operators Banks

Using Institution Codes

// Direct enum usage for type safety and IntelliSense
var request = new NameEnquiryRequest
{
    AccountNumber = "1234567890",
    Institution = InstitutionCodes.Mtn // Recommended approach
};

// Getting the string value of an institution code (e.g., for logging or specific API needs)
string mtnCodeString = InstitutionCodes.Mtn.ToString(); // Returns "300591"

// Parsing a string back to an enum (useful if codes come from configuration or external sources)
// Ensure robust error handling if parsing user input
if (Enum.TryParse("300304", out InstitutionCodes parsedBankCode))
{
    Console.WriteLine($"Parsed bank code: {parsedBankCode}"); // Output: GcbBankLimited
}

🌐 Channel Types

When specifying payment channels, use the Channels constants for clarity and consistency:

❓ Support

For any questions, issues, or assistance with the LibertePay SDK, please reach out to our support team:

📜 License

This SDK is open-sourced and licensed under the MIT License. For more details, please refer to the LICENSE file in the repository.