ZonmPay
Sign in

Receive money

Collection API

Request a payment from a customer's mobile money account. Zonmpay creates a pending transaction, pushes the request to the customer and notifies you when the state changes.

POSThttps://zonmpay.com/api/public/v1/mobilepayin

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

    Use your live key

    A sk_live_ key is issued once your business is verified. Every request moves real money, so keep the secret on your server only.

  3. 3

    Send the collection request

    POST the customer's phone number and the amount. The number is normalised to 255XXXXXXXXX and the network is detected automatically.

  4. 4

    Store the reference

    The response returns a unique reference with status PENDING. Save it against your order — it is how you query or reconcile the payment later.

  5. 5

    Wait for the final state

    Do not treat PENDING as paid. Wait for the webhook, or poll the Transaction Status API, before you release goods or services.

Request body

phonenumberstringRequired

Customer phone: 2557XXXXXXXX, 07XXXXXXXX or +2556XXXXXXXX

amountstring | numberRequired

Amount in TZS, greater than zero

Example request

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

Responses

Success
{
  "type": "success",
  "message": "Payment request sent successfully",
  "data": {
    "reference": "A1B2C3D4E5",
    "phonenumber": "255712345678",
    "amount": "5000.00",
    "currency": "TZS",
    "status": "PENDING",
    "channelprovider": "Vodacom Tanzania",
    "environment": "live",
    "created": "2026-09-19T14:30:45.000Z"
  }
}
Error
{
  "type": "error",
  "message": "Invalid phone number format",
  "data": { "error_code": "phone_invalid_format" }
}

Things that can go wrong

  • phone_invalid_formatThe phone number is not a valid Tanzanian mobile number.
  • amount_invalidThe amount is missing, zero, negative or not a number.
  • unauthorizedThe API key is missing or unknown.
All documentationDisbursement API