README

Installation

You can install the package via composer:

composer require uzhlaravel/maishapay

• if you want to have a live account, you need to register at https://www.maishapay.net/ or https://marchand.maishapay.online/dashboard
• if you want to have a sandbox account, you need to register at https://www.maishapay.net/ or https://marchand.maishapay.online/dashboard
• you need to get your public and secret keys from the dashboard
• you can set the gateway mode to 0 for sandbox and 1 for live

automated installation

php artisan maishapay:install

You can publish and run the migrations with:

php artisan vendor:publish --tag="maishapay-migrations"
php artisan migrate

You can publish the config file with:

php artisan vendor:publish --tag="maishapay-config"

This is the contents of the published config file:

return [

    'public_key' => env('MAISHAPAY_PUBLIC_KEY'),
    'secret_key' => env('MAISHAPAY_SECRET_KEY'),
    'gateway_mode' => env('MAISHAPAY_GATEWAY_MODE', 0),
    'base_url' => env('MAISHAPAY_BASE_URL', 'https://marchand.maishapay.online/api/collect'),
    'b2c_base_url' => env('MAISHAPAY_B2C_BASE_URL', 'https://marchand.maishapay.online/api/b2c'),
    'callback_url' => env('MAISHAPAY_CALLBACK_URL'),

];

Add these to your .env file:

MAISHAPAY_PUBLIC_KEY=your-public-key
MAISHAPAY_SECRET_KEY=your-secret-key
MAISHAPAY_GATEWAY_MODE=0
MAISHAPAY_CALLBACK_URL=https://yourapp.com/maishapay/callback
# Optional: only needed if the B2C base URL changes
# MAISHAPAY_B2C_BASE_URL=https://marchand.maishapay.online/api/b2c

Usage Mobile Money Payment

use Uzhlaravel\Maishapay\Maishapay;
use Uzhlaravel\Maishapay\Models\MaishapayTransaction;
use Uzhlaravel\Maishapay\DataTransferObjects\MobileMoney;
use Uzhlaravel\Maishapay\Exceptions\MaishapayException;

// you can use it as a parameter to a controller method

  protected $maishapay;

    public function __construct(Maishapay $maishapay)
    {
        $this->maishapay = $maishapay;
    }
    
    // for MOBILEMONEY payment type
      
    // validating the request data
    $validatedData = $request->validate([
            'amount' => 'required|numeric',
            'currency' => 'required|string',
            'customerFullName' => 'required|string',
            'customerEmailAddress' => 'required|email',
            'provider' => 'required|string',
            'walletID' => 'required',
            'channel' => 'required|string',
        ]);
        
    //if you want to keep track of the transaction
     $transaction = MaishapayTransaction::create([
                'payment_type' => 'MOBILEMONEY',
                'provider' => $validatedData['provider'],
                'amount' => $validatedData['amount'],
                'currency' => $validatedData['currency'],
                'customer_full_name' => $validatedData['customerFullName'],
                'customer_email' => $validatedData['customerEmailAddress'],
                'wallet_id' => $validatedData['walletID'],
                'channel' => $validatedData['channel'],
                'transaction_reference'=> 'TXN_' . uniqid(),
                'status' => 'PENDING'
            ]);
            
     //then do the transactin
     $mobileMoney = new MobileMoney(
                amount: $validatedData['amount'],
                currency: $validatedData['currency'],
                customerFullName: $validatedData['customerFullName'],
                customerEmailAddress: $validatedData['customerEmailAddress'],
                provider: $validatedData['provider'],
                walletId: $validatedData['walletID'],
                transactionReference: $transaction->transaction_reference,
                callbackUrl: route('pricing')
            );

            // Process mobile money payment
            $response = $this->maishapay->processMobileMoneyPayment($mobileMoney);

            // Parse the response
            $responseData = $response->json();
            
            
        // or you can use implemetation directly in your controller method
                   
            $maishapay = new Uzhlaravel\Maishapay\Maishapay();
        
             $response = $this->maishapay->processMobileMoneyPayment($mobileMoney);
             
             ...(other code)

Automate the database

use Uzhlaravel\Maishapay\EnhancedMaishapayService;
use Uzhlaravel\Maishapay\Models\MaishapayTransaction;
use Uzhlaravel\Maishapay\DataTransferObjects\MobileMoney;
use Uzhlaravel\Maishapay\Exceptions\MaishapayException;

// you can use it as a parameter to a controller method

  protected $maishapay;

    public function __construct(
    private EnhancedMaishapayService $enhancedMaishapayService,
    )
    {
    
    }
    
      
    // validating the request data
    $validatedData = $request->validate([
            'amount' => 'required|numeric',
            'currency' => 'required|string',
            'customerFullName' => 'required|string',
            'customerEmailAddress' => 'required|email',
            'provider' => 'required|string',
            'walletID' => 'required',
            'channel' => 'required|string',
        ]);
        
            
     //then do the transactin
     $mobileMoney = new MobileMoney(
                amount: $validatedData['amount'],
                currency: $validatedData['currency'],
                customerFullName: $validatedData['customerFullName'],
                customerEmailAddress: $validatedData['customerEmailAddress'],
                provider: $validatedData['provider'],
                walletId: $validatedData['walletID'],
                transactionReference: $transaction->transaction_reference,
                callbackUrl: route('pricing')
            );

            // Process mobile money payment
            $response = $this->enhancedMaishapayService->processMobileMoneyPaymentWithLogging($mobileMoney);

            // Parse the response
            $responseData = $response->json();
            
            
        // or you can use implemetation directly in your controller method
                   
            $maishapay = new Uzhlaravel\Maishapay\Maishapay();
        
             $response = $this->maishapay->processMobileMoneyPayment($mobileMoney);
             
             ...(other code)

Usage Bank Payment

//importing the class

use Uzhlaravel\Maishapay\Maishapay;
use Uzhlaravel\Maishapay\Models\MaishapayTransaction;
use Uzhlaravel\Maishapay\DataTransferObjects\MobileMoney;
use Uzhlaravel\Maishapay\Exceptions\MaishapayException;

// you can use it as a parameter to a controller method

// for BANK payment type V2

// validating the request data
$validatedData = $request->validate([
            'amount' => 'required|numeric',
            'currency' => 'required|string',
            'customerFullName' => 'required|string',
            'customerEmailAddress' => 'required|email',
            'provider' => 'required|string',
            'walletID' => 'required',
            'channel' => 'required|string',
        ]);
        
//  if you want to keep track
$transaction = MaishapayTransaction::query()->create([
                'payment_type' => 'CARD',
                'provider' => $validatedData['provider'], //visa or mastercard
                'amount' => $validatedData['amount'],
                'currency' => $validatedData['currency'],
                'customer_full_name' => $validatedData['customerFullName'],
                'customer_phone' => $validatedData['customerPhoneNumber'],
                'customer_email' => $validatedData['customerEmailAddress'],
                'channel' =>  $validatedData['channel'],
                'transaction_reference'=> 'TXN_' . uniqid(),
                'status' => 'PENDING'
            ]);

            $cardPayment = new CardPayment(
                amount: $validatedData['amount'],
                currency: $validatedData['currency'],
                customerEmailAddress: $validatedData['customerEmailAddress'],
                customerPhoneNumber: $validatedData['customerPhoneNumber'],
                provider: $validatedData['provider'],
                customerFullName: $validatedData['customerFullName'],
                transactionReference: $transaction->transaction_reference,
                callbackUrl: route('your-callback-route') // if different from the one in your .env file
            );

            $response = $this->maishapay->processCardPayment($cardPayment);

            $responseData = $response->json();        
            
            //make sure to redirect to the payment page : 
            
             return redirect($responseData['paymentPage']);
        (other code)

Automate the database transactions :

//importing the class

use Uzhlaravel\Maishapay\Services\EnhancedMaishapayService ;
use Uzhlaravel\Maishapay\DataTransferObjects\CardPayment;
use Uzhlaravel\Maishapay\Exceptions\MaishapayException;


 private EnhancedMaishapayService $enhancedMaishapayService;

 $cardPayment = new CardPayment(
                amount: $validatedData['amount'],
                currency: $validatedData['currency'],
                customerEmailAddress: $validatedData['customerEmailAddress'],
                customerPhoneNumber: $validatedData['customerPhoneNumber'],
                provider: $validatedData['provider'],
                customerFullName: $validatedData['customerFullName'],
                transactionReference: $transaction->transaction_reference,
                callbackUrl: route('your-callback-route') // if different from the one in your .env file
            );
            
            $response = $this->enhancedMaishapayService->processCardPaymentWithLogging($cardPayment,true);

            $responseData = $response->json();        
            
            //make sure to redirect to the payment page : 

Usage B2C (Business to Customer) Payment

B2C allows your business to send money directly to a customer's mobile money wallet — useful for payouts, refunds, salaries, or commissions.

use Uzhlaravel\Maishapay\Maishapay;
use Uzhlaravel\Maishapay\DataTransferObjects\BusinessToCustomer;
use Uzhlaravel\Maishapay\Exceptions\MaishapayException;

// Inject via constructor or resolve from container
public function __construct(Maishapay $maishapay)
{
    $this->maishapay = $maishapay;
}

// Validate request
$validatedData = $request->validate([
    'amount'                => 'required|numeric',
    'currency'              => 'required|string',
    'customer_full_name'    => 'required|string',
    'customer_email'        => 'required|email',
    'provider'              => 'required|string',   // AIRTEL, ORANGE, MTN, VODACOM
    'wallet_id'             => 'required|string',   // recipient phone / wallet number
    'motif'                 => 'required|string',   // reason for the transfer
]);

$b2c = new BusinessToCustomer(
    amount:               $validatedData['amount'],
    currency:             $validatedData['currency'],
    customerFullName:     $validatedData['customer_full_name'],
    customerEmailAddress: $validatedData['customer_email'],
    provider:             $validatedData['provider'],
    walletId:             $validatedData['wallet_id'],
    motif:                $validatedData['motif'],
    callbackUrl:          route('your-callback-route') // optional
);

try {
    $response = $this->maishapay->processB2CPayment($b2c);
    $responseData = $response->json();
    // handle success
} catch (MaishapayException $e) {
    // handle error
}

B2C with automatic database logging

use Uzhlaravel\Maishapay\Services\EnhancedMaishapayService;
use Uzhlaravel\Maishapay\DataTransferObjects\BusinessToCustomer;
use Uzhlaravel\Maishapay\Exceptions\MaishapayException;

public function __construct(private EnhancedMaishapayService $enhancedMaishapayService)
{
}

$b2c = new BusinessToCustomer(
    amount:               '5000',
    currency:             'CDF',
    customerFullName:     'Jane Doe',
    customerEmailAddress: 'jane@example.com',
    provider:             'AIRTEL',
    walletId:             '0999000000',
    motif:                'Monthly commission payout',
);

$result = $this->enhancedMaishapayService->processB2CPaymentWithLogging($b2c);

// Unlike collection, a B2C transfer resolves synchronously: the API returns
// the final status (SUCCESS or FAILED) in the same response, and the logged
// transaction is updated accordingly straight away.
if ($result['success']) {
    $transaction = $result['transaction']; // MaishapayTransaction model (SUCCESS)
    $apiResponse  = $result['response'];
} else {
    // $result['status'] is FAILED when the operator declined the transfer,
    // or $result['error'] is set when the request itself could not be sent.
    $status = $result['status'] ?? null;
    $error  = $result['error'] ?? null;
}

Note: For B2C, motif, customer_full_name and customer_email_address are optional (the MaishaPay API marks them as not required). amount, currency, provider and wallet_id remain required.

B2C using the static create() helper

$b2c = BusinessToCustomer::create([
    'amount'                => '5000',
    'currency'              => 'CDF',
    'provider'              => 'MTN',
    'wallet_id'             => '0810000000',
    // The following are all optional for B2C:
    'customer_full_name'    => 'Jane Doe',
    'customer_email_address'=> 'jane@example.com',
    'motif'                 => 'Refund for order #1234',
    'callback_url'          => 'https://yourapp.com/maishapay/callback',
]);

$response = $this->maishapay->processB2CPayment($b2c);

B2C database migration

Run the additional migration to support B2C transactions:

php artisan vendor:publish --tag="maishapay-migrations"
php artisan migrate

This adds:

• A motif column to maishapay_transactions
• B2C as a valid payment_type enum value

Querying B2C transactions

use Uzhlaravel\Maishapay\Models\MaishapayTransaction;

// All B2C transactions
$b2cTransactions = MaishapayTransaction::b2c()->get();

// B2C stats via EnhancedMaishapayService
$stats = $this->enhancedMaishapayService->getTransactionStats();
// $stats['b2c'] => total B2C transaction count

Checking transaction status from MaishaPay's servers

Instead of trusting the status stored in your local database, you can query the live status of a transaction directly from MaishaPay's Transaction Lookup API. This is useful when a callback was missed, delayed, or you simply want to confirm the real state before fulfilling an order. It works for any transaction type — Mobile Money, card, or B2C.

The lookup runs against MaishaPay's dedicated transaction endpoint (https://marchand.maishapay.online/api/transaction/rest/v2/check) and supports two modes:

• By merchant reference — your own transactionReference (sent with ?useRef=1). This is the default.
• By MaishaPay transaction ID — the numeric ID MaishaPay returns in the initial payment response.

Quick status check (raw response)

use Uzhlaravel\Maishapay\Facades\Maishapay;

// By your merchant reference (returns the raw Illuminate HTTP Response)
$response = Maishapay::checkTransactionStatus('MP_ABC123_1700000000');

// ...or by the MaishaPay transaction ID
$response = Maishapay::checkTransactionById(12345);

$status = $response->json('transactionStatus'); // e.g. "SUCCESS", "PENDING", "FAILED"

Canonical status via EnhancedMaishapayService

use Uzhlaravel\Maishapay\Services\EnhancedMaishapayService;

$service = app(EnhancedMaishapayService::class);

// Live status from the endpoint, normalized to PENDING|SUCCESS|FAILED|CANCELLED
$status = $service->getTransactionStatus('MP_ABC123_1700000000');

// Or get the status plus the raw payload
['status' => $status, 'response' => $payload] =
    $service->fetchTransactionStatus('MP_ABC123_1700000000');

Refresh the local record from the server

refreshTransactionStatus() queries MaishaPay, syncs the matching local MaishapayTransaction record (so the database acts as a cache), and fires the TransactionStatusUpdated event when the status changes:

$transaction = $service->refreshTransactionStatus('MP_ABC123_1700000000');

if ($transaction?->isSuccessful()) {
    // fulfil the order
}

Configuration

The Transaction Lookup base URL and endpoint are configurable:

The lookup posts gatewayMode, publicApiKey, secretApiKey and transactionId (set to your merchant reference, with ?useRef=1, when looking up by reference). The canonical status is read from MaishaPay's transactionStatus field and normalized to PENDING, SUCCESS, FAILED or CANCELLED.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• uzziahlukeka
• All Contributors

License

The MIT License (MIT). Please see License File for more information.