Documentation
Zonmpay API
One REST surface for collecting and sending money in Tanzania. Every endpoint uses the same authentication, the same JSON shape and the same reference, so you can go from a test call to production without rewriting your integration.
Before your first call
1. Create an account and a business
Sign up, confirm your email and create your business profile. Your wallet, keys and webhooks all live under that business.
2. Generate your API key
In the developer area generate a sk_live_ key. The secret is shown once — copy it straight into your server environment.
3. Call the API from your server only
Send the key as x-api-key on every request. Never place a secret key in browser code, a mobile app or a public repository.
Authentication
Every request carries your secret key. Only a hash of the key is stored on our side, so a lost key can be revoked but never recovered — generate a new one instead.
x-api-key: YOUR_API_KEY
Content-Type: application/json
# or, equivalently
Authorization: Bearer YOUR_API_KEYResponse shape
Successful and failed calls both return JSON with a type, a human-readable message and a data object. Errors carry an error_code you can branch on — internal database details are never exposed.
{
"type": "success" | "info" | "error",
"message": "Human readable summary",
"data": { }
}API keys
A sk_live_ key is issued once your business passes verification and every request it makes moves real money. Keep it on your server, rotate it if exposed.
Endpoints
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.
Disbursement API
Pay out from your Zonmpay wallet to a customer, agent or vendor. The payout is only accepted when your available balance covers it.
Transaction Status API
Look up any transaction that belongs to your business by its reference and read both the current state and the full timeline of how it got there.
Balance API
Read your wallet balance in real time. Balances are kept in exact minor units and returned per currency and per environment.
Number Lookup API
Resolve a mobile money number to its network before you pay out, and to the stored customer name when that number already exists in your customer list.
Webhook API
Instead of polling, let Zonmpay POST every payment event to your server. Each delivery is signed and retried, and every attempt is logged.
Note: every request you make with a live key moves real money. Confirm each transaction status through the webhook or the status endpoint before releasing goods or services.