Disbursement API

Step by step

1. 1

   Authenticate the request

   Send your secret key in the x-api-key header (or as Authorization: Bearer KEY). Keys are created in the developer area and shown only once — store yours server-side and never in browser code.

2. 2

   Confirm the recipient

   Call the Number Lookup API first so you send to the right person and network.

3. 3

   Check your balance

   Call the Balance API. A payout larger than the available balance is rejected with insufficient_funds — nothing is reserved.

4. 4

   Send the payout

   POST the phone number, amount and wallet PIN. You receive a reference with status PENDING.

5. 5

   Reconcile

   The PAYOUT webhook (or the Transaction Status API) tells you when it settles. Never mark the payout as sent from your frontend.

Request body

Example request

curl -X POST https://zonmpay.com/api/public/v1/mobilepayout \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "phonenumber": "255712345678",
    "amount": "10000",
    "pin": "1234"
  }'

Responses

{
  "type": "success",
  "message": "Payout accepted",
  "data": {
    "reference": "BAH72NSNSI",
    "amount": "10000.00",
    "fee": "0.00",
    "direction": "debit",
    "paymenttype": "API Payout",
    "status": "PENDING",
    "currency": "TZS",
    "channelprovider": "Vodacom Tanzania",
    "accountnumber": "255712345678",
    "environment": "live",
    "created": "2026-09-19T11:58:00.000Z"
  }
}

{
  "type": "error",
  "message": "Insufficient balance",
  "data": {
    "error_code": "insufficient_funds",
    "available": "0.00",
    "requested": "10000.00",
    "currency": "TZS"
  }
}

Things that can go wrong

• insufficient_fundsYour available balance is lower than the requested amount.
• pin_requiredThe wallet PIN is missing or not 4–6 digits.
• phone_invalid_formatThe recipient number is invalid.