Malipopay PHP SDK

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

Environment	Base URL
Production	https://core-prod.malipopay.co.tz
UAT	https://core-uat.malipopay.co.tz

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

Event	Description
payment.initiated	Payment has been initiated
payment.completed	Payment completed successfully
payment.failed	Payment failed
payment.reversed	Payment was reversed
collection.completed	Collection completed
collection.failed	Collection failed
disbursement.completed	Disbursement completed
disbursement.failed	Disbursement failed
invoice.paid	Invoice was fully paid
invoice.overdue	Invoice is overdue

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

Exception	HTTP Status	Description
AuthenticationException	401	Invalid or missing API key
PermissionException	403	Insufficient permissions
NotFoundException	404	Resource not found
ValidationException	422	Validation failed (check getFields())
RateLimitException	429	Rate limit exceeded (check getRetryAfter())
ApiException	5xx	Server error
ConnectionException	-	Network/timeout error

Testing

composer test

License

MIT - see LICENSE for details.

Copyright (c) 2026 Lockwood Technology Ltd.

---

See Also

SDK	Install
Node.js	npm install malipopay
Python	pip install malipopay
PHP	composer require malipopay/malipopay-php
Java	Maven / Gradle
.NET	dotnet add package Malipopay
Ruby	gem install malipopay

API Reference | OpenAPI Spec | Test Scenarios