API Integration

The direct API integration gives you full control over the payment flow.

Base URL

https://core-prod.malipopay.co.tz

Every path carries its version. These docs describe v2, so a collection is POST /api/v2/payment/collection.

Collection flow

Your Server → POST /api/v2/payment/collection → MALIPOPAY → MNO/Bank
                                                     ↓
Your Webhook ← POST (payment status)     ← MALIPOPAY

Disbursement flow

Your Server → POST /api/v2/payment/disbursement → AWAITING_APPROVAL
Your Server → POST /api/v2/payment/approve       → APPROVED → MNO/Bank
   (from a whitelisted IP)                              ↓
Your Webhook ← POST (payout status)              ← MALIPOPAY

Request format

All requests use a JSON body with Content-Type: application/json and your key in the apiToken header.

Response format

All responses follow this structure:

{
  "success": true,
  "code": 1109,
  "message": "Collection request sent successfully",
  "data": { }
}

code is a MALIPOPAY status code and is more specific than the HTTP status. The ones you will meet most often:

Code	Meaning
1109	Collection accepted
1120	Disbursement created, awaiting approval
1111	Disbursement or batch accepted
1117	Disbursement approved and dispatched
1112	Disbursement rejected

Error responses

{
  "success": false,
  "code": 400,
  "message": "Invalid phone number format"
}

See Error Handling for a full list of error codes.