README

The official PHP SDK for the Malipopay payment platform (Tanzania).

Requirements

• PHP 8.0 or later
• cURL extension
• JSON extension

Installation

composer require malipopay/malipopay-php

Quick Start

use Malipopay\Malipopay;

$client = new Malipopay('your_api_key');

// Collect mobile money
$payment = $client->payments->collect([
    'amount' => 50000,
    'currency' => 'TZS',
    'phoneNumber' => '255712345678',
    'reference' => 'ORDER-001',
    'callbackUrl' => 'https://yourapp.com/webhooks/malipopay',
]);

Configuration

$client = new Malipopay('your_api_key', [
    'environment' => 'uat',          // 'production' (default) or 'uat'
    'base_url' => 'https://...',     // Override base URL
    'timeout' => 60,                 // Request timeout in seconds (default: 30)
    'retries' => 3,                  // Retry attempts on 429/5xx (default: 2)
    'webhook_secret' => 'whsec_...', // Webhook verification secret
]);

Environments

Resources

Payments

// Initiate a payment
$client->payments->initiate([...]);

// Collect (mobile money pull)
$client->payments->collect([
    'amount' => 50000,
    'currency' => 'TZS',
    'phoneNumber' => '255712345678',
    'reference' => 'ORDER-001',
    'callbackUrl' => 'https://yourapp.com/callback',
]);

// Disburse funds
$client->payments->disburse([
    'amount' => 25000,
    'currency' => 'TZS',
    'phoneNumber' => '255712345678',
    'reference' => 'DISB-001',
]);

// Pay now (instant)
$client->payments->payNow([...]);

// Verify a payment
$client->payments->verify('PAY-REF-001');

// Get payment by reference
$client->payments->get('PAY-REF-001');

// List / search payments
$client->payments->list(['page' => 1, 'limit' => 20]);
$client->payments->search(['status' => 'completed']);

// Approve and confirm approval
$client->payments->approve(['reference' => 'PAY-REF-001', 'otp' => '123456']);
$client->payments->confirmApproval([...]);

// Retry a failed payment
$client->payments->retry('PAY-REF-001');

// Create payment link
$client->payments->createLink([
    'amount' => 100000,
    'currency' => 'TZS',
    'description' => 'Product purchase',
]);

Customers

$client->customers->create([
    'name' => 'John Doe',
    'phoneNumber' => '255712345678',
    'email' => 'john@example.com',
]);

$client->customers->list();
$client->customers->get('customer_id');
$client->customers->getByNumber('CUST-001');
$client->customers->getByPhone('255712345678');
$client->customers->search(['name' => 'John']);
$client->customers->verify('255712345678');

Invoices

// Get next invoice number
$nextNo = $client->invoices->nextInvoiceNo();

// Create an invoice
$client->invoices->create([
    'invoiceNo' => $nextNo,
    'customerName' => 'Acme Corp',
    'dueDate' => '2026-05-01',
    'currency' => 'TZS',
    'items' => [
        ['description' => 'Service', 'quantity' => 1, 'unitPrice' => 500000],
    ],
]);

$client->invoices->list();
$client->invoices->get('invoice_id');
$client->invoices->getByNumber('INV-001');
$client->invoices->update('invoice_id', ['dueDate' => '2026-06-01']);
$client->invoices->recordPayment([
    'invoiceId' => 'invoice_id',
    'amount' => 500000,
    'paymentMethod' => 'mobile_money',
]);
$client->invoices->approveDraft(['invoiceId' => 'invoice_id']);

Products

$client->products->create([
    'name' => 'Premium Plan',
    'price' => 100000,
    'currency' => 'TZS',
]);

$client->products->list();
$client->products->get('product_id');
$client->products->getByNumber('PROD-001');
$client->products->update([...]);

Transactions

$client->transactions->list();
$client->transactions->get('txn_id');
$client->transactions->search(['type' => 'credit', 'from' => '2026-01-01']);
$client->transactions->paginate(['page' => 1, 'limit' => 50]);
$client->transactions->tariffs();

Account

$client->account->transactions();
$client->account->searchTransactions(['from' => '2026-01-01']);
$client->account->getTransaction('txn_id');
$client->account->reconciliation();
$client->account->financialPosition();
$client->account->incomeStatement();
$client->account->generalLedger();
$client->account->trialBalance();

SMS

$client->sms->send([
    'to' => '255712345678',
    'message' => 'Your payment of TZS 50,000 was received.',
]);

$client->sms->sendBulk([
    'recipients' => ['255712345678', '255713456789'],
    'message' => 'Bulk message',
]);

$client->sms->schedule([
    'to' => '255712345678',
    'message' => 'Scheduled message',
    'sendAt' => '2026-04-15T09:00:00Z',
]);

$client->sms->list();
$client->sms->get('sms_id');
$client->sms->search(['status' => 'delivered']);

References

$client->references->banks();
$client->references->institutions();
$client->references->currencies();
$client->references->countries();
$client->references->businessTypes();

Webhooks

Verify and process incoming webhook events:

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_MALIPOPAY_SIGNATURE'] ?? '';

try {
    $event = $client->webhooks->constructEvent($payload, $signature);

    switch ($event['type']) {
        case 'payment.completed':
            // Handle completed payment
            break;
        case 'payment.failed':
            // Handle failed payment
            break;
        case 'collection.completed':
            // Handle completed collection
            break;
        case 'disbursement.completed':
            // Handle completed disbursement
            break;
        case 'invoice.paid':
            // Handle paid invoice
            break;
    }

    http_response_code(200);
} catch (\Malipopay\Exceptions\MalipopayException $e) {
    http_response_code(400);
}

Webhook Event Types

Error Handling

All errors extend Malipopay\Exceptions\MalipopayException:

use Malipopay\Exceptions\AuthenticationException;
use Malipopay\Exceptions\ValidationException;
use Malipopay\Exceptions\RateLimitException;
use Malipopay\Exceptions\MalipopayException;

try {
    $client->payments->collect([...]);
} catch (AuthenticationException $e) {
    // 401 - Invalid API key
} catch (ValidationException $e) {
    // 422 - Check $e->getFields() for field-level errors
} catch (RateLimitException $e) {
    // 429 - Retry after $e->getRetryAfter() seconds
} catch (MalipopayException $e) {
    // Any other API error
    echo $e->getMessage();
    echo $e->getStatusCode();
}

Exception Classes

Testing

composer test

License

MIT - see LICENSE for details.

Copyright (c) 2026 Lockwood Technology Ltd.

See Also

API Reference | OpenAPI Spec | Test Scenarios