Zhuwa.Moolre.Sdk 1.0.0-beta.1

This is a prerelease version of Zhuwa.Moolre.Sdk.
dotnet add package Zhuwa.Moolre.Sdk --version 1.0.0-beta.1
                    
NuGet\Install-Package Zhuwa.Moolre.Sdk -Version 1.0.0-beta.1
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Zhuwa.Moolre.Sdk" Version="1.0.0-beta.1" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Zhuwa.Moolre.Sdk" Version="1.0.0-beta.1" />
                    
Directory.Packages.props
<PackageReference Include="Zhuwa.Moolre.Sdk" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Zhuwa.Moolre.Sdk --version 1.0.0-beta.1
                    
#r "nuget: Zhuwa.Moolre.Sdk, 1.0.0-beta.1"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Zhuwa.Moolre.Sdk@1.0.0-beta.1
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Zhuwa.Moolre.Sdk&version=1.0.0-beta.1&prerelease
                    
Install as a Cake Addin
#tool nuget:?package=Zhuwa.Moolre.Sdk&version=1.0.0-beta.1&prerelease
                    
Install as a Cake Tool

Zhuwa.Moolre.Sdk

An unofficial, community-built .NET client for the Moolre API, maintained by Zhuwa Africa. It covers all 31 documented Moolre operations: mobile money collections, payment links, Payment IDs and bank collections, transfers, wallets, airtime and data, SMS and WhatsApp, plus payment webhooks.

This project is independent. It is not affiliated with, endorsed by, or supported by Moolre.

Requirements

  • .NET 10 or later. Works with trimming and Native AOT.
  • Moolre API credentials for your wallet (created in the Moolre app; each wallet has its own).

Installation

dotnet add package Zhuwa.Moolre.Sdk --prerelease

Usage

Register the SDK once, then inject MoolreClient:

using Zhuwa.Moolre;
using Zhuwa.Moolre.DependencyInjection;
using Zhuwa.Moolre.Payments;

builder.Services.AddMoolre(options =>
{
    options.Environment = MoolreEnvironment.Sandbox;   // the default; Live is an explicit choice
    options.ApiUser = builder.Configuration["Moolre:ApiUser"];
    options.PublicKey = builder.Configuration["Moolre:PublicKey"];
    options.AccountNumber = builder.Configuration["Moolre:AccountNumber"];
});

public class CheckoutService(MoolreClient moolre)
{
    public async Task StartAsync(string orderId, CancellationToken cancellationToken)
    {
        var result = await moolre.Payments.RequestMobileMoneyAsync(new RequestMobileMoneyRequest
        {
            Channel = PaymentChannel.Mtn,
            Currency = Currency.Ghs,
            PayerPhoneNumber = "0241234567",
            Amount = 25.50m,
            ExternalReference = orderId,   // unique per payment; keep it
        }, cancellationToken);

        // result.Outcome: PromptSent, or OtpRequired (send again with the customer's code)
    }
}

Several wallets: register each with AddMoolre("name", ...) and use MoolreClientFactory.Create("name").

Exception handling

Exception Meaning
MoolreOutcomeUncertainException A money or message call may or may not have happened (timeout, dropped connection). Check its status with the same reference; never resend blindly.
MoolreDuplicateReferenceException The reference was already used. Look up the original.
MoolreAuthenticationException Credentials or wallet rejected.
MoolreApiException Moolre refused the call; for money calls, nothing moved.
MoolreResponseException Moolre's answer could not be read.

Calls that move money or send messages are never retried by the SDK. Every Moolre call is a POST, so do not add a blind retry policy to its HttpClient.

Webhooks

builder.Services.AddMoolreWebhooks(o => o.Secret = builder.Configuration["Moolre:CallbackSecret"]);

// In your endpoint, with the raw body bytes and the X-Moolre-Signature header:
if (verifier.IsSignatureValid(body, signature) && PaymentWebhook.TryParse(body, out var webhook) && webhook.IsSuccessfulPayment)
{
    // confirm with Payments.GetStatusAsync, then fulfil once
}

Documentation

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.0.0-beta.1 0 11/17/2026

First version:
- All 31 documented Moolre operations: mobile money collections (with the OTP flow), payment links, Payment IDs and bank collection accounts, transfers and name validation, wallets and transaction history, airtime and data, SMS and WhatsApp.
- Payment webhooks: parsing and X-Moolre-Signature verification (HMAC-SHA256, constant time, replay window), one secret per wallet.
- Money safety: calls that move money or send messages are never retried; an unknown outcome throws MoolreOutcomeUncertainException with your reference.
- Several wallets through named clients (AddMoolre(name, ...) and MoolreClientFactory).
- Dependency injection first, trimming and Native AOT compatible, credentials never logged.

Full history: https://github.com/zhuwaafrica/moolre-dotnet-sdk/blob/main/CHANGELOG.md