PochiNet API
Accept mobile money payments from your website or app across Tanzania: M-Pesa, Mixx by Yas, Airtel Money and HaloPesa, through one simple API.
Your customer gets a PIN prompt on their phone and approves it. You find out the result with a webhook, or by checking the status yourself.
Maelezo mafupi kwa Kiswahili
- Fungua akaunti PochiNet na uthibitishe email kwa msimbo wa tarakimu 6.
- Pakia nyaraka zako na ulipe ada ya mara moja ya activation.
- Akaunti ikishaidhinishwa, tengeneza API key kwenye Dashboard, sehemu ya Developers. Inaonyeshwa mara moja tu.
- Tuma
POST /paymentsnanumber(namba ya mteja),amount(TZS) nareference(namba ya oda yako, isirudiwe). - Mteja anapata ombi la PIN kwenye simu yake. Hali ya malipo ni
PENDING, kishaCOMPLETEDauFAILED. - Weka webhook URL kwenye Dashboard ili upate taarifa malipo yakikamilika. Thibitisha kila mara saini kwenye kichwa
X-PochiNet-Signature. Pia unaweza kuuliza hali kwaGET /payments/{reference}. - Weka API key kwenye seva yako tu, kamwe si kwenye app au tovuti ya mteja. Msaada: .
Getting started
- Create an account on PochiNet and verify your email with the 6-digit code we send you.
- Submit your documents (ID, plus business details if you are registered) and pay the one-time activation fee shown in your dashboard.
- Once your account is approved, open Dashboard → Developers and generate your API key. It is shown only once, so copy it straight away.
- Optionally, save your webhook URL in the same place.
- Send your first payment request.
Authentication
Send your API key in the Authorization header of every request.
Authorization: Bearer pn_live_xxxxxxxxxxxxxxxx Content-Type: application/json
A missing or wrong key returns 401 with the code unauthorized.
Create a payment
Sends a payment request to the customer's phone. The response comes back straight away with the status PENDING while the customer approves.
| Field | Type | Description |
|---|---|---|
numberrequired | string | The customer's mobile money number, local (0754123456) or international (255754123456). |
amountrequired | integer | Amount in TZS, between 100 and 5,000,000. |
referencerequired | string | Your own unique ID for this payment, for example your order number. 1 to 60 characters: letters, digits, . _ -. A reference can be used only once. |
nameoptional | string | The customer's name, up to 100 characters. |
200{
"status": true,
"data": {
"reference": "ORDER-1042",
"amount": 20000,
"fee": 600,
"net": 19400,
"status": "PENDING"
}
}| Field | Description |
|---|---|
reference | The reference you sent. |
amount | The amount the customer pays. |
fee | The PochiNet fee for this payment, in TZS. |
net | The amount credited to your wallet if the payment succeeds. |
status | Always PENDING when the request is created. |
The numbers above are only an illustration. fee and net come back with every payment, calculated for your account.
Check payment status
Returns the current state of one of your payments. Use it to confirm a payment, or if you missed a webhook.
200{
"status": true,
"data": {
"reference": "ORDER-1042",
"amount": 20000,
"fee": 600,
"net": 19400,
"status": "COMPLETED",
"number": "255754123456",
"type": "payment"
}
}If the reference does not exist on your account you get 404 with the code not_found.
Payment statuses
| Status | Meaning |
|---|---|
| PENDING | Waiting for the customer to approve on their phone. |
| COMPLETED | The money was received and net was added to your wallet. Safe to deliver the order. |
| FAILED | The customer cancelled or declined, or the payment could not be completed. Nothing was charged. |
COMPLETED and FAILED are final: a payment never changes again after reaching one of them.
Webhooks
A webhook is a request we send to your server when a payment is finished, so you do not have to keep asking.
Set it up
- Open Dashboard → Developers → Webhook and enter your URL. It must start with
https://and use a public domain (not an IP address orlocalhost). - The first time you save, a webhook secret (starting with
whsec_) is shown once. Store it safely: you need it to verify the signature. Use New secret to replace it.
Events
| Event | When |
|---|---|
payment.completed | A payment succeeded. |
payment.cancelled | A payment failed or was cancelled. |
payout.completed | A withdrawal you requested was paid. |
payout.failed | A withdrawal was rejected and the money returned to your wallet. |
Request we send you
An HTTP POST with a JSON body and the header X-PochiNet-Signature.
{
"event": "payment.completed",
"timestamp": "2026-11-15T09:30:12.000Z",
"data": {
"reference": "ORDER-1042",
"amount": 20000,
"fee": 600,
"net": 19400,
"status": "COMPLETED",
"number": "255754123456",
"type": "payment"
}
}2xx status within 8 seconds. We try once and do not retry, so if your server was down you will miss that event. Use Check payment status to catch up, for example when the customer comes back to your site or on a regular schedule.Verify the signature
Anyone can call your webhook URL, so check that the request really came from PochiNet. Compute an HMAC-SHA256 of the raw request body using your webhook secret, add the prefix sha256=, and compare it with the X-PochiNet-Signature header using a constant-time comparison.
- Use the raw body exactly as received. Do not parse and re-encode it before checking.
- Reject the request with
401if the signature does not match. - Before delivering an order, check that the
referenceis one of yours and theamountmatches the order. - Make your handler idempotent: if the same event arrives twice, do the work only once.
Errors
Failed requests return a JSON body with status: false, a machine-readable code and a readable message.
{ "status": false, "code": "invalid_amount", "message": "Amount must be between TZS 100 and 5,000,000." }| HTTP | Code | What to do |
|---|---|---|
| 401 | unauthorized | The API key is missing or wrong. Check the Authorization header. |
| 403 | kyc_required | Your account is not approved yet. Finish verification in the dashboard. |
| 403 | email_unverified | Verify your email first. |
| 403 | account_disabled | The account is suspended. Contact support. |
| 404 | not_found | The payment or endpoint does not exist. |
| 409 | duplicate_reference | That reference was already used. Fetch it with GET /payments/{reference}, or send a new reference. |
| 422 | invalid_amount invalid_number invalid_reference | Fix the field named in the message and try again. |
| 429 | rate_limited | Too many requests. Wait a minute and retry. |
| 502 | provider_error | The mobile network could not accept the request. Try again. |
| 500 | server_error | Something went wrong on our side. Try again, and contact support if it continues. |
429 or 502, that reference is closed. Retry with a new reference.Testing
There is no sandbox: requests are live and move real money. Test with a small amount and your own number:
- Generate your API key and run the create payment example with your own mobile money number and an amount such as 1,000.
- Approve the PIN prompt on your phone.
- Call check status until it shows
COMPLETED, and confirm that your wallet shows thenetamount in the dashboard. - Try cancelling a second prompt and see the status become
FAILED.
https address. During development, use a tunnel tool such as ngrok or Cloudflare Tunnel to expose your local server, and save that address as your webhook URL.Some networks may reject very small amounts. If a request fails with provider_error, try 1,000 or more.
Best practices
- Keep the API key and webhook secret in environment variables, not in your code.
- Save the
referencewith your order before you call the API, and use it to match the webhook back to the order. - Do not treat the customer returning to your site as proof of payment. Confirm with a webhook or check status.
- Show a clear "Check your phone and enter your PIN" message while the status is
PENDING. Customers take a moment to respond. - Log the raw webhook body. It makes problems much easier to trace.
Withdrawals
You collect through the API, and you withdraw from the dashboard. Open Wallet, enter the number, network, name and amount. Each request is reviewed and paid by our team, and you can follow its status in the dashboard. If you set a webhook, you also receive payout.completed or payout.failed. A rejected withdrawal returns the full amount to your wallet.
Support
Questions or something not working? Email and include your payment reference so we can find it quickly.