malipopay 1.0.0

Official Python SDK for the MaliPoPay payment platform (Tanzania)

MaliPoPay Python SDK

Official Python SDK for the MaliPoPay payment platform. Accept payments via Mobile Money (M-Pesa, Airtel Money, Mixx/YAS, Halopesa, T-Pesa), Bank Transfer (CRDB, NMB), USSD, and Card (Visa, Mastercard) in Tanzania.

Installation

pip install malipopay

Quick Start

from malipopay import MaliPoPay

client = MaliPoPay("your-api-key")

# Collect payment via mobile money
payment = client.payments.collect({
    "description": "Order #1234",
    "amount": 10000,
    "phoneNumber": "255712345678",
})

print(payment["reference"])  # "PAY-abc123"

Async Usage

import asyncio
from malipopay import AsyncMaliPoPay

async def main():
    async with AsyncMaliPoPay("your-api-key") as client:
        payment = await client.payments.collect({
            "description": "Order #1234",
            "amount": 10000,
            "phoneNumber": "255712345678",
        })
        print(payment["reference"])

asyncio.run(main())

Configuration

client = MaliPoPay(
    "your-api-key",
    environment="uat",           # "production" (default) or "uat"
    timeout=30.0,                # Request timeout in seconds (default: 30)
    retries=2,                   # Auto-retry on 5xx/429 (default: 2)
    webhook_secret="whsec_...",  # For webhook signature verification
)

Usage

Payments

# Collect payment
payment = client.payments.collect({
    "description": "Order #1234",
    "amount": 10000,
    "phoneNumber": "255712345678",
})

# Disburse funds
payout = client.payments.disburse({
    "description": "Salary payment",
    "amount": 50000,
    "phoneNumber": "255712345678",
})

# Verify payment status
status = client.payments.verify("PAY-abc123")

# Search payments
results = client.payments.search({
    "status": "COMPLETED",
    "from": "2026-01-01",
    "to": "2026-03-31",
})

# Create payment link
link = client.payments.create_link({
    "amount": 25000,
    "phoneNumber": "255712345678",
})

Customers

# Create customer
customer = client.customers.create({
    "phoneNumber": "255712345678",
    "firstname": "John",
    "lastname": "Doe",
    "email": "[e-mail]",
})

# Search customers
customers = client.customers.search({"query": "John"})

# Verify customer
verified = client.customers.verify("255712345678")

Invoices

# Create invoice
invoice = client.invoices.create({
    "customer": "customer-id",
    "items": [
        {"description": "Web Development", "quantity": 1, "unitPrice": 500000},
    ],
    "dueDate": "2026-05-01",
    "currency": "TZS",
    "taxRate": 18,
})

# Record payment against invoice
client.invoices.record_payment({
    "invoiceId": "invoice-id",
    "amount": 500000,
    "reference": "PAY-abc123",
})

Products

product = client.products.create({
    "name": "Monthly Subscription",
    "price": 25000,
    "currency": "TZS",
    "category": "subscription",
})

Transactions

transactions = client.transactions.list()
tx = client.transactions.get("tx-id")
search = client.transactions.search({"status": "COMPLETED"})

Account

balance = client.account.transactions()
reconciliation = client.account.reconciliation()

SMS

# Send single SMS
client.sms.send({
    "sender": "MALIPOPAY",
    "phoneNumber": "255712345678",
    "message": "Your payment was received!",
})

# Send bulk SMS
client.sms.send_bulk({
    "sender": "MALIPOPAY",
    "phoneNumber": ["255712345678", "255713456789"],
    "message": "Special offer!",
})

Reference Data

banks = client.references.banks()
currencies = client.references.currencies()
countries = client.references.countries()

Webhook Handling

from malipopay import MaliPoPay

client = MaliPoPay("your-api-key", webhook_secret="whsec_your_secret")

# Verify and parse webhook
event = client.webhooks.construct_event(
    payload=raw_body,                                  # request body as string or bytes
    signature=request.headers["x-malipopay-signature"],  # signature header
)

if event["type"] == "payment.completed":
    print("Payment completed:", event["data"])
elif event["type"] == "payment.failed":
    print("Payment failed:", event["data"])

Flask Example

from flask import Flask, request
from malipopay import MaliPoPay, MaliPoPayError

app = Flask(__name__)
client = MaliPoPay("your-api-key", webhook_secret="whsec_your_secret")

@app.route("/webhooks", methods=["POST"])
def handle_webhook():
    try:
        event = client.webhooks.construct_event(
            payload=request.get_data(as_text=True),
            signature=request.headers.get("x-malipopay-signature", ""),
        )
        print(f"Event: {event['type']}")
        return {"received": True}
    except MaliPoPayError as e:
        return {"error": str(e)}, 400

Error Handling

from malipopay import MaliPoPay, AuthenticationError, ValidationError

try:
    client.payments.collect({...})
except AuthenticationError:
    print("Invalid API key")
except ValidationError as e:
    print(f"Validation failed: {e.message}")

Error types: AuthenticationError (401), PermissionError (403), NotFoundError (404), ValidationError (422), RateLimitError (429), ApiError (5xx), ConnectionError (network).

Requirements

• Python 3.8+
• MaliPoPay API key (get one here)

License

MIT

---

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