API docs Sign inGet an API key

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.

Base URL
FormatJSON over HTTPS
CurrencyTZS (whole shillings)

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
  1. Fungua akaunti PochiNet na uthibitishe email kwa msimbo wa tarakimu 6.
  2. Pakia nyaraka zako na ulipe ada ya mara moja ya activation.
  3. Akaunti ikishaidhinishwa, tengeneza API key kwenye Dashboard, sehemu ya Developers. Inaonyeshwa mara moja tu.
  4. Tuma POST /payments na number (namba ya mteja), amount (TZS) na reference (namba ya oda yako, isirudiwe).
  5. Mteja anapata ombi la PIN kwenye simu yake. Hali ya malipo ni PENDING, kisha COMPLETED au FAILED.
  6. Weka webhook URL kwenye Dashboard ili upate taarifa malipo yakikamilika. Thibitisha kila mara saini kwenye kichwa X-PochiNet-Signature. Pia unaweza kuuliza hali kwa GET /payments/{reference}.
  7. Weka API key kwenye seva yako tu, kamwe si kwenye app au tovuti ya mteja. Msaada: .

Getting started

  1. Create an account on PochiNet and verify your email with the 6-digit code we send you.
  2. Submit your documents (ID, plus business details if you are registered) and pay the one-time activation fee shown in your dashboard.
  3. Once your account is approved, open Dashboard → Developers and generate your API key. It is shown only once, so copy it straight away.
  4. Optionally, save your webhook URL in the same place.
  5. 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
Keep your key secretUse it only from your server. Never put it in a mobile app, a web page or a public repository. If it leaks, generate a new key in the dashboard: the old one stops working immediately.

A missing or wrong key returns 401 with the code unauthorized.

Create a payment

POST/payments

Sends a payment request to the customer's phone. The response comes back straight away with the status PENDING while the customer approves.

Body parameters
FieldTypeDescription
numberrequiredstringThe customer's mobile money number, local (0754123456) or international (255754123456).
amountrequiredintegerAmount in TZS, between 100 and 5,000,000.
referencerequiredstringYour own unique ID for this payment, for example your order number. 1 to 60 characters: letters, digits, . _ -. A reference can be used only once.
nameoptionalstringThe customer's name, up to 100 characters.
Response 200
{
  "status": true,
  "data": {
    "reference": "ORDER-1042",
    "amount": 20000,
    "fee": 600,
    "net": 19400,
    "status": "PENDING"
  }
}
FieldDescription
referenceThe reference you sent.
amountThe amount the customer pays.
feeThe PochiNet fee for this payment, in TZS.
netThe amount credited to your wallet if the payment succeeds.
statusAlways 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

GET/payments/{reference}

Returns the current state of one of your payments. Use it to confirm a payment, or if you missed a webhook.

Response 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

StatusMeaning
PENDINGWaiting for the customer to approve on their phone.
COMPLETEDThe money was received and net was added to your wallet. Safe to deliver the order.
FAILEDThe 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

  1. Open Dashboard → Developers → Webhook and enter your URL. It must start with https:// and use a public domain (not an IP address or localhost).
  2. 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

EventWhen
payment.completedA payment succeeded.
payment.cancelledA payment failed or was cancelled.
payout.completedA withdrawal you requested was paid.
payout.failedA 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"
  }
}
Reply quickly, and do not rely on webhooks aloneAnswer with any 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 401 if the signature does not match.
  • Before delivering an order, check that the reference is one of yours and the amount matches 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." }
HTTPCodeWhat to do
401unauthorizedThe API key is missing or wrong. Check the Authorization header.
403kyc_requiredYour account is not approved yet. Finish verification in the dashboard.
403email_unverifiedVerify your email first.
403account_disabledThe account is suspended. Contact support.
404not_foundThe payment or endpoint does not exist.
409duplicate_referenceThat reference was already used. Fetch it with GET /payments/{reference}, or send a new reference.
422invalid_amount invalid_number invalid_referenceFix the field named in the message and try again.
429rate_limitedToo many requests. Wait a minute and retry.
502provider_errorThe mobile network could not accept the request. Try again.
500server_errorSomething went wrong on our side. Try again, and contact support if it continues.
Use a new reference for each attemptWhen a request fails with 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:

  1. Generate your API key and run the create payment example with your own mobile money number and an amount such as 1,000.
  2. Approve the PIN prompt on your phone.
  3. Call check status until it shows COMPLETED, and confirm that your wallet shows the net amount in the dashboard.
  4. Try cancelling a second prompt and see the status become FAILED.
Testing webhooks on your computerWebhooks need a public 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 reference with 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.