Skip to main content

Quickstart

Step 1: Sign up​

Create your MALIPOPAY account at app.malipopay.co.tz.

Step 2: Get your API key​

In the dashboard, go to Settings → API Keys and copy your secret key. It looks like mp_sk_prod_... and goes in the apiToken header on every request.

Step 3: Add a test recipient​

Until your account is approved for go-live, you can only transact with numbers you have registered under Settings → Test Recipients (up to three), and each direction is capped at TZS 100,000 per day. Add the phone number you are going to charge before you make the call. See Testing.

Step 4: Make your first collection request​

curl -X POST https://core-prod.malipopay.co.tz/api/v2/payment/collection \
  -H "apiToken: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "ORDER-001",
    "description": "Payment for Order #001",
    "amount": 50000,
    "service": "mobile",
    "account": "255712345678",
    "amountType": "FULL"
  }'

You do not need to say which network the number belongs to. For service: "mobile" the MNO is detected from the number, and 0712345678 is accepted just as readily as 255712345678. To charge a bank account or a till instead, change service to account or merchant and add provider (for example "provider": "CRDB").

The call returns as soon as the request reaches the channel. The customer has not paid yet:

{
  "success": true,
  "code": 1109,
  "message": "Collection request sent successfully",
  "data": {
    "merchantAccountId": "Lockwood Technology",
    "mode": "CHARGE",
    "amountType": "FULL",
    "reference": "ML008985",
    "amount": 50000,
    "paidAmount": 0,
    "transactionFee": 1250,
    "customer": {
      "phoneNumber": "255712345678",
      "firstname": "JOHN",
      "lastname": "HAULE",
      "mno": "Vodacom"
    },
    "description": "Payment for Order #001",
    "link": "https://app.malipopay.co.tz/ref?ML008985",
    "currency": "TZS",
    "status": "PROCESSING",
    "id": "6890f1c2a4b19e3f2c7d5a10",
    "createdAt": "2026-08-18T08:15:32.000Z",
    "updatedAt": "2026-08-18T08:15:32.000Z",
    "available_channels": ["VODACOM", "AIRTEL", "TIGO", "CRDB"]
  }
}

Store data.reference. It is how you match the webhook and how support traces the payment.

Step 5: Handle the webhook​

Configure your webhook URL in the dashboard. MALIPOPAY POSTs to it when the payment reaches a final state:

{
  "timestamp": "20260818081604",
  "reference": "ML008985",
  "customerReference": "ORDER-001",
  "amount": 50000,
  "merchantAccountId": "Lockwood Technology",
  "status": "SUCCESSFUL",
  "type": "CHARGE",
  "customer": {
    "firstname": "JOHN",
    "lastname": "HAULE",
    "phoneNumber": "255712345678",
    "mno": "Vodacom"
  },
  "transactionId": "MP250001234567",
  "payloadSignature": "b875460229adc88cef4bd9904b0b06ba4b2cb4...",
  "event": "payment.confirmed",
  "service": "Collection"
}

Verify the X-Malipopay-Signature header before trusting it. See Webhooks.

Step 6: Go live​

Submit for go-live approval in the dashboard. Nothing about your integration changes: same base URL, same API key. Approval lifts the test-recipient restriction and raises your limits. See Going Live.

Success
You're live!
Last updated on