README

A Laravel 11+ package for the ZenoPay payment gateway — Mobile Money, Utility Payments, Disbursements, and SMS.

Features

Requirements

• PHP 8.2+
• Laravel 11.x or 12.x

Installation

composer require shadrack-mballah/zenopay-laravel

Publish the config file:

php artisan vendor:publish --tag=zenopay-config

Add to .env:

ZENOPAY_API_KEY=your_api_key_here
ZENOPAY_WALLET_PIN=1234
ZENOPAY_WEBHOOK_URL=https://your-domain.com/zenopay/webhook

Usage

Mobile Money Collection

use ShadrackMballah\ZenoPay\Facades\ZenoPay;

// Initiate USSD push payment
$response = ZenoPay::mobileMoney()->collect(
    orderId:    (string) \Str::uuid(),
    buyerPhone: '0744963858',
    amount:     5000,
    buyerName:  'John Doe',
);

if ($response->isSuccess()) {
    // Payment request sent — await webhook for COMPLETED status
    $orderId = $response->orderId;
}

// Check payment status
$status = ZenoPay::mobileMoney()->orderStatus($orderId);

if ($status->isCompleted()) {
    // Payment confirmed
}

Webhook Handling

// routes/api.php
Route::post('/zenopay/webhook', ZenoPayWebhookController::class)
    ->withoutMiddleware('auth');

// app/Http/Controllers/ZenoPayWebhookController.php
use ShadrackMballah\ZenoPay\Webhooks\WebhookHandler;

class ZenoPayWebhookController extends Controller
{
    public function __invoke(Request $request)
    {
        $payload = WebhookHandler::parse($request);

        if ($payload->isCompleted()) {
            // Update your order as paid
            Order::where('zenopay_order_id', $payload->orderId)
                ->update(['status' => 'paid', 'payment_reference' => $payload->reference]);
        }

        return response()->json(['received' => true]);
    }
}

Utility Payments

use ShadrackMballah\ZenoPay\Services\UtilityPaymentService;

// Look up a LUKU meter before charging
$lookup = ZenoPay::utility()->lookupMeter('12345678', (string) \Str::uuid());

if ($lookup->isValid()) {
    // $lookup->customerName is the meter owner name

    // Pay electricity
    $result = ZenoPay::utility()->payElectricity(
        transId:     (string) \Str::uuid(),
        meterNumber: '12345678',
        amount:      10000,
        msisdn:      '0744963858',
    );
}

// Pay DSTV
ZenoPay::utility()->payDstv($transId, $smartCardNo, 50000, $msisdn);

// Buy airtime
ZenoPay::utility()->buyAirtime($transId, '0744963858', 1000);

// Pay government bill (GEPG)
ZenoPay::utility()->payGepg($transId, $controlNumber, $amount, $msisdn);

// Custom utility
ZenoPay::utility()->pay($transId, UtilityPaymentService::STARTIMES, $ref, $amount, $msisdn);

Disbursements

// Send money to any Tanzanian mobile wallet
$result = ZenoPay::disbursement()->send(
    transId: (string) \Str::uuid(),
    phone:   '0744963858',
    amount:  25000,
);

if ($result->isSuccess()) {
    // $result->walletBalance — your remaining balance
    // $result->amountDelivered — amount received by customer
}

SMS

// Single SMS
ZenoPay::sms()->send(
    recipient: '255744963858',
    message:   'Your LUKU token: 1234-5678-9012',
    senderId:  'MYAPP',
);

// Bulk SMS
ZenoPay::sms()->sendBulk(
    recipients: ['255744963858', '255712345678'],
    message:    'Your payment has been received.',
    senderId:   'MYAPP',
);

// Request a new sender ID
ZenoPay::sms()->requestSenderId('MYAPP', 'Transactional alerts for MYAPP');

Supported Utility Codes

License

MIT