API v1

Mapesa Hapa API

Pokea Mobile Money na toa pesa kwa namba ya simu kwa endpoint chache tu. Authentication ni Bearer token, response ni JSON.

1. Quickstart

Jisajili kupata account.
Nenda Dashboard ubonyeze Generate API Key.
Hifadhi key yako (mfano: mph_live_xxxx) — itaonekana mara moja tu.
Jaribu endpoint ya /balance kuhakiki imefanya kazi.

2. Authentication

Kila request lazima iwe na header ya Authorization yenye API key yako:

Authorization: Bearer mph_live_xxxxxxxxxxxxxxxx
Content-Type: application/json

Hifadhi keys server-side tu. Usiweke kwenye browser au mobile app.

GET/balance

Pata balance ya wallet yako (TZS).

Response

{
  "status": "success",
  "data": { "balance_tzs": 12450, "currency": "TZS" }
}

POST/deposits

Anzisha collection ya Mobile Money. USSD push itatumwa moja kwa moja kwa mteja.

Request body

{
  "amount": 5000,
  "method": "mobile",
  "phone": "255712345678",
  "reference": "ORDER-001",
  "callback_url": "https://app.yako/webhook"
}

Response

{
  "status": "success",
  "data": {
    "id": "tx_01HZABC...",
    "status": "pending",
    "amount_tzs": 5000,
    "reference": "ORDER-001"
  }
}

Status ya mwisho (completed au failed) itatumwa kwenye callback_url yako. Inawekwa kwenye wallet yako pale tu mteja anapokamilisha malipo.

POST/withdrawals

Toa pesa kutoka kwenye wallet yako kwenda namba ya simu. Inafanyika kiotomatiki.

Request body

{
  "amount": 5000,
  "method": "mobile",
  "recipient": "255712345678",
  "reference": "PAYOUT-001"
}

Response

{
  "status": "success",
  "data": {
    "id": "tx_01HZDEF...",
    "status": "pending",
    "amount_tzs": 5000,
    "fee_tzs": 200
  }
}

Ada ni 4% ya kiasi unachotoa. Wallet yako itakatwa kiasi + ada papo hapo. Withdrawal ikishindikana, pesa zinarudishwa kwenye wallet.

GET/transactions

Pata orodha ya transactions zako za hivi karibuni (deposits + withdrawals).

Response

{
  "status": "success",
  "data": [
    {
      "id": "tx_01HZABC...",
      "type": "deposit",
      "amount_tzs": 5000,
      "status": "completed",
      "reference": "ORDER-001",
      "created_at": "2026-06-04T10:00:00Z"
    }
  ]
}

Webhooks

Ukiweka callback_url kwenye request ya deposit, tutakupigia POST pale transaction inapokamilika au kushindwa:

{
  "event": "transaction.completed",
  "data": {
    "id": "tx_01HZABC...",
    "type": "deposit",
    "amount_tzs": 5000,
    "status": "completed",
    "reference": "ORDER-001"
  }
}

Jibu na 200 OK ndani ya sekunde 5. Tukikosa, tutajaribu tena kwa exponential backoff.

Errors

{
  "error": "insufficient_balance",
  "message": "Wallet haina pesa za kutosha."
}

401 — API key haipo au imebatilishwa
402 — Wallet haina pesa za kutosha (withdrawal)
422 — Validation error (field hazikamiliki)
429 — Umezidi rate limit (60 req/min)

Base URL

https://mapesahapa.online/api/v1

Support

Una swali, tatizo la integration, au unahitaji higher rate limits? Tuandikie:

support@mapesahapa.online

Tunajibu ndani ya saa 24. Tafadhali jumuisha request_id au tx_id kama unaripoti tatizo la transaction.