AlrajhiMokafaa 1.0.2

Alrajhi Mokafaa API Client

A comprehensive C# client library for integrating with Alrajhi Bank's Mokafaa Earn and Burn APIs.

Installation

NuGet Package (Recommended)

dotnet add package AlrajhiMokafaa

Or via Package Manager Console:

Install-Package AlrajhiMokafaa

Or add to your .csproj file:

<ItemGroup>
  <PackageReference Include="AlrajhiMokafaa" Version="1.0.0" />
</ItemGroup>

Build from Source

git clone https://github.com/yourusername/AlrajhiMokafaa.git
cd AlrajhiMokafaa
dotnet build

Features

• Burn API (Redemption)

  • Authorize Customer
  • Redeem Customer Amount (OTP Validation)
  • Reverse Redemption Transaction
  • Get Redemption Transaction Details
  • Get Redemption Transactions List

• Earn API (Accruals)

  • Earn by SAR
  • Earn by Points
  • Earn by SAR and Ratio
  • Refund Earn by SAR
  • Get Earn Transaction Details
  • Get Earn Reconciliation

Configuration

Add the following configuration to your appsettings.json:

{
  "AlrajhiMokafaa": {
    "SIT": {
      "BurnApiBaseUrl": "https://your-earn-api-base-url-here",
      "EarnApiBaseUrl": "https://your-burn-api-base-url-here",
      "ClientId": "your-client-id",
      "ClientSecret": "your-client-secret",
      "MerchantToken": "your-merchant-token",
      "PartnerCode": "your-partner-code",
      "LocationCode": "your-location-code",
      "BurnApiScopes": "customer-authorization-v2 otp-validation-v2 redemption-transaction-reversal-v2 get-redemption-transactions-list get-redemption-transaction-details",
      "EarnApiScopes": "earn-by-sar earn-by-points earn-by-sar-and-ratio refund-earn-by-sar get-earn-trans-details get-earn-recon"
    },
    "Production": {
      "BurnApiBaseUrl": "https://your-earn-api-base-url-here",
      "EarnApiBaseUrl": "https://your-burn-api-base-url-here",
      "ClientId": "your-client-id",
      "ClientSecret": "your-client-secret",
      "MerchantToken": "your-merchant-token",
      "PartnerCode": "your-partner-code",
      "LocationCode": "your-location-code",
      "BurnApiScopes": "customer-authorization-v2 otp-validation-v2 redemption-transaction-reversal-v2 get-redemption-transactions-list get-redemption-transaction-details",
      "EarnApiScopes": "earn-by-sar earn-by-points earn-by-sar-and-ratio refund-earn-by-sar get-earn-trans-details get-earn-recon"
    },
    "BusinessRules": {
      "MinimumRedemptionAmount": 1.00,
      "MaxOtpAttempts": 3,
      "OtpExpiryMinutes": 3,
      "ReversalWindowHours": 24
    },
    "Security": {
      "PrivateKeyName": "AlrajhiMokafaaPrivateKey",
      "PrivateKey": "your-private-key-pem-content"
    }
  }
}

Usage

Basic Setup

using AlrajhiMokafaa.Services;
using AlrajhiMokafaa.Models.Configuration;
using System.Net.Http;

// Load configuration from appsettings.json or create manually
var settings = new AlrajhiMokafaaSettings
{
    SIT = new EnvironmentSettings
    {
        BurnApiBaseUrl = "https://your-burn-api-base-url-here",
        EarnApiBaseUrl = "https://your-earn-api-base-url-here",
        ClientId = "your-client-id",
        ClientSecret = "your-client-secret",
        MerchantToken = "your-merchant-token",
        PartnerCode = "your-partner-code",
        LocationCode = "your-location-code",
        BurnApiScopes = "customer-authorization-v2 otp-validation-v2 redemption-transaction-reversal-v2 get-redemption-transactions-list get-redemption-transaction-details",
        EarnApiScopes = "earn-by-sar earn-by-points earn-by-sar-and-ratio refund-earn-by-sar get-earn-trans-details get-earn-recon"
    }
};

var httpClient = new HttpClient();
var service = new AlrajhiMokafaaService(httpClient, settings, useProduction: false);

Burn API Examples

Authorize Customer

var request = new AuthorizeCustomerRequest
{
    Mobile = "your-mobile-number",
    Language = "en"
};

var response = await service.Burn.AuthorizeCustomerAsync(request);

if (response.IsSuccess)
{
    var otpToken = response.Data.OTPToken;
    var customerName = response.Data.CustomerName;
    var availableBalance = response.Data.AvailableBalance;
}
else
{
    Console.WriteLine($"Error: {response.ErrorMessage}");
}

Redeem Customer Amount

var request = new RedeemCustomerAmountRequest
{
    OTPValue = "1234",
    OTPToken = "otp-token-from-authorize",
    Amount = "20.0",
    Language = "en",
    RedeemTrnNo = Guid.NewGuid().ToString()
};

var response = await service.Burn.RedeemCustomerAmountAsync(request);

if (response.IsSuccess)
{
    var transactionId = response.Data.TransactionID;
    var amount = response.Data.Amount;
}

Reverse Redemption

var request = new ReverseRedemptionRequest
{
    TransactionID = "your-transaction-id",
    ReverseTrnNo = Guid.NewGuid().ToString()
};

var response = await service.Burn.ReverseRedemptionTransactionAsync(request);

Get Transaction Details

var response = await service.Burn.GetRedemptionTransactionDetailsAsync(
    trnNo: "your-transaction-number",
    partnerCode: "your-partner-code"
);

Get Transactions List

var response = await service.Burn.GetRedemptionTransactionsListAsync(
    fromDate: DateTime.Now.AddDays(-7),
    toDate: DateTime.Now,
    pageNumber: 1,
    pageSize: 100
);

Earn API Examples

Earn by SAR

var request = new EarnBySarRequest
{
    Mobile = "your-mobile-number",
    Amount = 100.00m,
    Language = "en",
    EarnTrnNo = Guid.NewGuid().ToString()
};

var response = await service.Earn.EarnBySarAsync(request);

if (response.IsSuccess)
{
    var points = response.Data.Points;
    var transactionId = response.Data.TransactionID;
}

Earn by Points

var request = new EarnByPointsRequest
{
    Mobile = "your-mobile-number",
    Points = 1000m,
    Language = "en",
    EarnTrnNo = Guid.NewGuid().ToString()
};

var response = await service.Earn.EarnByPointsAsync(request);

Earn by SAR and Ratio

var request = new EarnBySarAndRatioRequest
{
    Mobile = "your-mobile-number",
    Amount = 100.00m,
    Ratio = 0.1m, // 10% ratio
    Language = "en",
    EarnTrnNo = Guid.NewGuid().ToString()
};

var response = await service.Earn.EarnBySarAndRatioAsync(request);

Refund Earn

var request = new RefundEarnBySarRequest
{
    TransactionID = "transaction-id",
    RefundTrnNo = Guid.NewGuid().ToString()
};

var response = await service.Earn.RefundEarnBySarAsync(request);

Get Earn Transaction Details

var response = await service.Earn.GetEarnTransactionDetailsAsync(
    trnNo: "your-transaction-number",
    partnerCode: "your-partner-code"
);

Get Earn Reconciliation

var response = await service.Earn.GetEarnReconciliationAsync(
    fromDate: DateTime.Now.AddDays(-7),
    toDate: DateTime.Now,
    partnerCode: "your-partner-code"
);

Error Handling

All API methods return an ApiResponse<T> object that includes:

• IsSuccess: Boolean indicating if the request was successful
• Data: The response data (if successful)
• ErrorMessage: Error message (if failed)
• ErrorCode: Error code (if available)
• HttpStatusCode: HTTP status code (if available)

var response = await service.Burn.AuthorizeCustomerAsync(request);

if (!response.IsSuccess)
{
    Console.WriteLine($"Error Code: {response.ErrorCode}");
    Console.WriteLine($"Error Message: {response.ErrorMessage}");
    Console.WriteLine($"HTTP Status: {response.HttpStatusCode}");
}

Notes

• The service automatically handles OAuth token generation and caching
• Dates are automatically set to UTC if not provided
• LocationCode and PartnerCode are automatically populated from settings if not provided
• Signature generation is optional and only used if a private key is provided in configuration