ISP Gateway Handbook Mwongozo wa Dalipay

One handbook for operators, merchants, and developers. Mwongozo mmoja kwa wasimamizi, wafanyabiashara, na wabunifu wa mifumo.

Everything you need to run the platform, manage a merchant account, and integrate mobile money collections & disbursements (AzamPay) into your own systems — with copy-paste request examples for the Collections API.

Kila kitu unachohitaji kuendesha mfumo, kusimamia akaunti ya mfanyabiashara, na kuunganisha malipo ya pesa za simu (collections) na utoaji wa fedha (disbursements) kupitia AzamPay kwenye mifumo yako — ikiwa na mifano ya maombi (requests) ya Collections API unayoweza kunakili na kubandika.

AdminMsimamizi

Platform operationsUendeshaji wa mfumo

Approve merchants, review KYC, release settlements, and monitor the platform ledger.

Kuthibitisha wafanyabiashara, kukagua KYC, kuruhusu malipo ya kutoa fedha, na kufuatilia kumbukumbu za mfumo mzima.

Open admin guide Fungua mwongozo wa msimamizi MerchantMfanyabiashara

Merchant dashboardDashibodi ya mfanyabiashara

API keys, IP whitelisting, team access, collections, and requesting settlements (Toa Pesa).

Funguo za API, uorodheshaji wa IP, ufikiaji wa timu, malipo yanayopokelewa, na kuomba kutoa fedha (Toa Pesa).

Open merchant guide Fungua mwongozo wa mfanyabiashara DeveloperMwendelezaji

Integration guideMwongozo wa muunganisho

Authenticate, create collections, poll status, handle disbursements & verify webhooks.

Kuthibitisha utambulisho, kuunda malipo, kuangalia hali, kushughulikia utoaji wa fedha & kuhakiki webhooks.

Open integration guide Fungua mwongozo wa muunganisho
AdminMsimamizi

Platform overviewMuhtasari wa mfumo

The admin panel is where the platform operator manages merchants, reviews KYC, approves settlement requests, and keeps an eye on money moving through the gateway across every merchant and environment.

Dashibodi ya msimamizi ni mahali anaposimamia wafanyabiashara, kukagua KYC, kuthibitisha maombi ya kutoa fedha, na kufuatilia mwendo wa fedha kupitia mfumo kwa kila mfanyabiashara na mazingira yote (test na production).

First-time setupUsanidi wa mara ya kwanza

The very first admin account is created via a one-time setup endpoint that disables itself once an admin exists.

Akaunti ya kwanza ya msimamizi inaundwa kupitia njia (endpoint) ya usanidi inayotumika mara moja tu, ambayo hujizima yenyewe pindi akaunti ya msimamizi ikiwepo.

POST /api/v1/setup/admin No auth (one-time)Hauhitaji utambulisho (mara moja)
FieldTypeDescriptionMaelezo
namestringRequiredInahitajikaFull name of the operator.Jina kamili la msimamizi.
emailstringRequiredInahitajikaLogin email for the admin account.Barua pepe ya kuingia kwenye akaunti ya msimamizi.
passwordstringRequiredInahitajikaMinimum 8 characters.Angalau herufi 8.
Once any admin account exists, this endpoint permanently returns an error. Run it immediately after deploying the platform, then sign in normally below.
Mara akaunti yoyote ya msimamizi ikiwepo, njia hii itarudisha kosa kwa kudumu. Itumie mara moja baada ya kufunga mfumo, kisha ingia kawaida kwa chini.

Signing inKuingia

POST /api/v1/auth/admin/login No authHauhitaji utambulisho

Returns a JWT used as a Bearer token for every other admin endpoint and for the /admin/* pages in the dashboard.

Inarudisha JWT inayotumika kama tokeni ya Bearer kwa njia zote nyingine za msimamizi na kwa kurasa za /admin/* kwenye dashibodi.

Dashboard at a glanceDashibodi kwa muhtasari

The admin dashboard summarizes activity across all merchants and both environments:

Dashibodi ya msimamizi inaonyesha muhtasari wa shughuli za wafanyabiashara wote na mazingira yote mawili:

  • Total collections & disbursements — success totals, counts, and cumulative platform fees.
  • Pending attention — collections awaiting customer confirmation, disbursements awaiting approval, and recent failures.
  • Money movement chart — a 14-day view of collection volume.
  • Merchant count — total registered merchants and their status breakdown.
  • Jumla ya malipo na utoaji wa fedha — jumla ya thamani, idadi, na ada za mfumo zilizokusanywa.
  • Mambo yanayosubiri — malipo yanayosubiri uthibitisho wa mteja, utoaji wa fedha unaosubiri idhini, na makosa ya hivi karibuni.
  • Chati ya mwendo wa fedha — muonekano wa siku 14 za malipo.
  • Idadi ya wafanyabiashara — jumla ya wafanyabiashara waliosajiliwa na hali zao.
AdminMsimamizi

Merchants & KYCWafanyabiashara & KYC

Every business that signs up gets a merchant account with separate test and production environments. Production access for collections and settlements depends on KYC status.

Kila biashara inayojisajili hupata akaunti yenye mazingira mawili tofauti — test na production. Ufikiaji wa production kwa malipo na utoaji wa fedha unategemea hali ya KYC.

Reviewing a merchantKukagua mfanyabiashara

From Merchants, an admin can open any merchant to see:

Kutoka Merchants, msimamizi anaweza kufungua mfanyabiashara yeyote na kuona:

  • Business details (name, contact, phone, country) and registration date.
  • Current KYC status: unverified, pending, or verified.
  • Current balance, fee percentage, and account status (active / suspended).
  • API keys issued (without revealing secret keys) and configured webhook URL.
  • Taarifa za biashara (jina, mawasiliano, simu, nchi) na tarehe ya usajili.
  • Hali ya sasa ya KYC: unverified, pending, au verified.
  • Salio la sasa, asilimia ya ada, na hali ya akaunti (active / suspended).
  • Funguo za API zilizotolewa (bila kuonyesha funguo za siri) na webhook URL iliyowekwa.
Why KYC matters: a merchant can use test mode freely as soon as they register — test collections and settlements are simulated instantly with no real money movement. Production collections work once a merchant has live API keys, but production settlements (Toa Pesa) are blocked until KYC status is verified.
Kwa nini KYC ni muhimu: mfanyabiashara anaweza kutumia test mode mara anaposajili — malipo na utoaji wa fedha kwenye test huigizwa papo hapo bila fedha halisi kuhamishwa. Malipo ya production hufanya kazi pindi mfanyabiashara akiwa na funguo za live, lakini kutoa fedha kwenye production (Toa Pesa) hakuruhusiwi mpaka hali ya KYC iwe verified.

Verifying KYCKuthibitisha KYC

  1. Open the merchant's profile and review the submitted business details against your onboarding checklist (business registration, contact verification, etc.).
  2. Update the merchant's KYC status to verified once checks pass. This immediately unblocks production settlement requests from their dashboard.
  3. If something is missing, leave the status as pending and follow up with the merchant — they'll see a "complete KYC" notice on their Disbursements page.
  1. Fungua wasifu wa mfanyabiashara na kagua taarifa za biashara zilizowasilishwa kulingana na orodha yako ya ukaguzi (usajili wa biashara, uthibitisho wa mawasiliano, n.k.).
  2. Badilisha hali ya KYC ya mfanyabiashara kuwa verified baada ya ukaguzi kufaulu. Hii itaruhusu mara moja maombi ya kutoa fedha kwenye production kutoka dashibodi yao.
  3. Iwapo kuna kinachokosekana, baki na hali pending na mfuatilie mfanyabiashara — wataona arifa ya "complete KYC" kwenye ukurasa wao wa Disbursements.

Suspending an accountKusimamisha akaunti

If a merchant needs to be paused (suspicious activity, non-payment, etc.), set their account status to suspended. This blocks new API requests and dashboard logins while preserving their transaction history.

Iwapo mfanyabiashara anahitaji kusimamishwa (shughuli za kutatanisha, kutolipa, n.k.), badilisha hali ya akaunti yao kuwa suspended. Hii itazuia maombi mapya ya API na kuingia kwenye dashibodi, huku ikitunza historia yote ya miamala.

AdminMsimamizi

Settlement & disbursement approvalsUthibitisho wa kutoa fedha

Production disbursements — whether sent via the API or requested as a merchant settlement ("Toa Pesa") — go to awaiting_approval by default. Funds are held from the merchant's balance immediately, so nothing can be double-spent while it's queued for review.

Utoaji wa fedha kwenye production — iwe ulitumwa kupitia API au kuombwa na mfanyabiashara kama "Toa Pesa" — huingia kwenye awaiting_approval kwa default. Fedha hutengwa kutoka salio la mfanyabiashara mara moja, ili kuzuia matumizi mara mbili wakati ombi linasubiri ukaguzi.

Reviewing the queueKukagua orodha inayosubiri

The Approvals page lists every disbursement in awaiting_approval, across all merchants, with:

Ukurasa wa Approvals unaorodhesha kila utoaji wa fedha ulio kwenye awaiting_approval, kwa wafanyabiashara wote, ukionyesha:

  • Merchant name and environment.
  • Recipient name, phone number, and mobile money provider.
  • Amount and platform fee.
  • Merchant reference (their external_id, or a settle_... reference if it was a dashboard settlement request).
  • Jina la mfanyabiashara na mazingira (test/production).
  • Jina la mpokeaji, namba ya simu, na mtandao wa pesa za simu.
  • Kiasi na ada ya mfumo.
  • Kumbukumbu ya mfanyabiashara (external_id yao, au kumbukumbu ya settle_... iwapo ni ombi la kutoka dashibodi).

ApproveKuthibitisha

Approving sends the payout to AzamPay immediately. On success, the disbursement moves to success and the held funds are permanently deducted. On failure, the disbursement moves to failed and the held amount is automatically refunded back to the merchant's balance.

Kuthibitisha hutuma malipo kwa AzamPay mara moja. Ikifanikiwa, utoaji wa fedha utabadilika kuwa success na fedha zilizotengwa zitakatwa kabisa. Ikishindwa, utoaji wa fedha utabadilika kuwa failed na kiasi kilichotengwa kitarejeshwa kiotomatiki kwenye salio la mfanyabiashara.

RejectKukataa

Rejecting a request moves it to rejected and immediately refunds the held amount (principal + fee) back to the merchant's available balance. Use this for requests that fail manual review (e.g. mismatched recipient details).

Kukataa ombi hubadilisha hali yake kuwa rejected na kurejesha mara moja kiasi kilichotengwa (kiasi + ada) kwenye salio la mfanyabiashara. Itumie kwa maombi yasiyofaulu ukaguzi wa kawaida (mfano, taarifa za mpokeaji hazilingani).

awaiting_approval
Held, queued for review
success
Sent to AzamPay, funds deducted
failed
Send failed, funds refunded
rejected
Declined, funds refunded
awaiting_approval
Imetengwa, inasubiri ukaguzi
success
Imetumwa AzamPay, fedha zimekatwa
failed
Imeshindwa, fedha zimerejeshwa
rejected
Imekataliwa, fedha zimerejeshwa
AdminMsimamizi

Platform ledgerKumbukumbu za mfumo

The Collections and Disbursements pages under Ledger give a platform-wide view across every merchant, with the same filters merchants see on their own ledgers plus a merchant filter.

Kurasa za Collections na Disbursements chini ya Ledger zinaonyesha muonekano wa mfumo mzima kwa wafanyabiashara wote, na vichujio (filters) sawa na vile wafanyabiashara wanavyoona kwenye kumbukumbu zao, pamoja na kichujio cha mfanyabiashara.

  • Filter by merchant, environment (test / production), and status.
  • Search by gateway reference, merchant reference, recipient name, or phone number.
  • Each row shows the net amount, platform fee, and timestamps — useful for reconciling AzamPay settlement reports against what the gateway recorded.
  • Chuja (Filter) kwa mfanyabiashara, mazingira (test / production), na hali.
  • Tafuta (Search) kwa kumbukumbu ya mfumo, kumbukumbu ya mfanyabiashara, jina la mpokeaji, au namba ya simu.
  • Kila mstari unaonyesha kiasi halisi (net), ada ya mfumo, na muda — muhimu kwa kulinganisha ripoti za AzamPay na kumbukumbu za mfumo.
Collections move from processing to success/failed asynchronously, once AzamPay's callback arrives after the customer confirms (or cancels) the USSD prompt on their phone. A collection sitting in processing for a long time usually means the customer never responded to the prompt.
Malipo hubadilika kutoka processing kwenda success/failed kwa njia ya asynchronous, mara webhook ya AzamPay ikifika baada ya mteja kuthibitisha (au kughairi) ombi la USSD kwenye simu yake. Malipo yaliyobaki processing kwa muda mrefu kwa kawaida humaanisha mteja hakujibu ombi.
MerchantMfanyabiashara

Merchant dashboard overviewMuhtasari wa dashibodi ya mfanyabiashara

Every merchant account has two independent environments — Test and Live — switchable from a toggle in the sidebar. Test mode simulates every outcome instantly with no real money movement, so you can build and demo your integration safely before going live.

Kila akaunti ya mfanyabiashara ina mazingira mawili tofauti — Test na Live — yanayobadilishwa kwa kitufe kwenye upande wa kushoto (sidebar). Test mode huigiza matokeo yote papo hapo bila fedha halisi kuhamishwa, ili uweze kujenga na kuonyesha muunganisho wako salama kabla ya kuingia Live.

  • Dashboard — balance, collection & disbursement totals, pending items, and a 14-day money-movement chart.
  • Collections — every incoming mobile money payment, with status and provider.
  • Disbursements — payouts sent via the API, plus self-service settlement requests.
  • API keys, IP whitelisting, Team, Settings — manage how your systems and people connect.
  • Dashboard — salio, jumla ya malipo na utoaji wa fedha, mambo yanayosubiri, na chati ya siku 14.
  • Collections — kila malipo ya pesa za simu yaliyopokelewa, pamoja na hali na mtandao.
  • Disbursements — fedha zilizotumwa kupitia API, pamoja na maombi ya kutoa fedha (settlement) ya mwenyewe.
  • API keys, IP whitelisting, Team, Settings — simamia jinsi mifumo yako na watu wanavyounganishwa.
MerchantMfanyabiashara

Register & log inJisajili & ingia

Create an accountFungua akaunti

POST /api/v1/auth/merchant/register No authHauhitaji utambulisho
FieldTypeDescriptionMaelezo
business_namestringRequiredInahitajikaYour registered business / ISP name.Jina la biashara/ISP yako iliyosajiliwa.
contact_namestringRequiredInahitajikaPrimary contact person.Mtu wa mawasiliano wa msingi.
emailstringRequiredInahitajikaUsed for login and notifications.Inatumika kuingia na kupata arifa.
phonestringRequiredInahitajikaTanzanian phone number.Namba ya simu ya Tanzania.
passwordstringRequiredInahitajikaMinimum 8 characters.Angalau herufi 8.
countrystringOptionalSi lazimaDefaults to Tanzania.Hutumia Tanzania kama chaguo-msingi.

New accounts start with kyc_status: unverified and a Test environment ready to use immediately — generate a test API key and start integrating right away.

Akaunti mpya huanza na kyc_status: unverified na mazingira ya Test tayari kutumika mara moja — tengeneza funguo za API za test na anza muunganisho mara moja.

Log inIngia

POST /api/v1/auth/merchant/login No authHauhitaji utambulisho

Send email and password — returns a JWT used as a Bearer token for the dashboard and all /merchant/* endpoints.

Tuma email na password — inarudisha JWT inayotumika kama tokeni ya Bearer kwa dashibodi na njia zote za /merchant/*.

MerchantMfanyabiashara

Dashboard & balanceDashibodi & salio

The dashboard's headline numbers always reflect the currently selected environment (Test or Live) — switch in the sidebar to see each side independently.

Namba kuu za dashibodi huonyesha mazingira yaliyochaguliwa kwa sasa (Test au Live) — badilisha kwenye sidebar ili kuona kila upande peke yake.

  • Available balance — funds from successful collections, net of platform fees, minus any amounts held for disbursements/settlements. This is what you can withdraw.
  • Collections (success) — total value and count of successful incoming payments.
  • Disbursements (success) — total value and count of completed payouts.
  • Platform fees — cumulative fees charged on collections and disbursements in this environment.
  • Pending attention — collections awaiting customer confirmation, disbursements awaiting admin approval, and recent failures, so you always know what needs a look.
  • Salio linalopatikana (Available balance) — fedha kutoka malipo yaliyofanikiwa, baada ya kutoa ada za mfumo, ukiondoa kiasi chochote kilichotengwa kwa utoaji wa fedha. Hii ndiyo unayoweza kutoa.
  • Collections (success) — jumla ya thamani na idadi ya malipo yaliyofanikiwa.
  • Disbursements (success) — jumla ya thamani na idadi ya utoaji wa fedha uliokamilika.
  • Platform fees — jumla ya ada zilizotozwa kwenye malipo na utoaji wa fedha kwa mazingira haya.
  • Mambo yanayosubiri — malipo yanayosubiri uthibitisho wa mteja, utoaji wa fedha unaosubiri idhini ya msimamizi, na makosa ya hivi karibuni, ili ujue kinachohitaji uangalizi wako.
Balance updates the moment AzamPay confirms a collection as successful (via webhook callback) — usually a few seconds after the customer approves the USSD prompt on their phone.
Salio hubadilika mara AzamPay inapothibitisha malipo kuwa yamefanikiwa (kupitia webhook) — kwa kawaida ndani ya sekunde chache baada ya mteja kukubali ombi la USSD kwenye simu yake.
MerchantMfanyabiashara

API keysFunguo za API

API keys authenticate requests from your systems to the Collections & Disbursements API. Each key pair is scoped to one environment.

Funguo za API zinathibitisha maombi kutoka mifumo yako kwenda Collections & Disbursements API. Kila jozi ya funguo inahusiana na mazingira moja tu (test au production).

  1. Go to API keys and choose Generate API key for the environment you need (Test or Live).
  2. The secret key is shown only once — copy both X-Public-Key and X-Secret-Key into your application's configuration / secrets manager immediately.
  3. Use these two values as request headers on every Collections / Disbursements API call (see the Integration guide).
  4. If a key pair is compromised, revoke it from the same page and generate a new one — revoked keys stop working immediately.
  1. Fungua API keys na chagua Generate API key kwa mazingira unayohitaji (Test au Live).
  2. Funguo ya siri (secret key) inaonyeshwa mara moja tu — nakili X-Public-Key na X-Secret-Key kwenye mfumo wako wa kuhifadhi siri mara moja.
  3. Tumia thamani hizi mbili kama vichwa (headers) vya kila ombi la Collections / Disbursements API (tazama Mwongozo wa muunganisho).
  4. Iwapo jozi ya funguo imevuja, ifute (revoke) kwenye ukurasa huo na utengeneze mpya — funguo zilizofutwa huacha kufanya kazi mara moja.
Treat X-Secret-Key like a password. Never embed it in frontend/mobile code — only call the Collections API from your backend server.
Tunza X-Secret-Key kama nenosiri. Usiweke kamwe kwenye msimbo wa frontend/mobile — piga simu API hii kutoka kwenye server yako ya nyuma (backend) tu.
MerchantMfanyabiashara

IP whitelistingUorodheshaji wa IP

For an extra layer of security, restrict which server IP addresses are allowed to use your API keys.

Kwa ulinzi wa ziada, punguza ni anwani za IP za seva zipi zinaruhusiwa kutumia funguo zako za API.

  • Add the public IP address(es) of the server(s) that will call the Collections / Disbursements API on your behalf.
  • Once at least one IP is whitelisted for an environment, requests from any other IP using that environment's keys are rejected — even with valid keys.
  • Leave the list empty to allow requests from any IP (useful while developing, not recommended for production).
  • Ongeza anwani ya IP ya umma ya seva(s) zitakazopiga Collections / Disbursements API kwa niaba yako.
  • Mara IP moja ikiwa imeorodheshwa kwa mazingira fulani, maombi kutoka IP nyingine yoyote yanayotumia funguo za mazingira hayo yatakataliwa — hata kama funguo ni sahihi.
  • Acha orodha tupu kuruhusu maombi kutoka IP yoyote (inafaa wakati wa maendeleo, haishauriwi kwa production).
If you move your integration to a new server (or test it from a different machine, like a local API console), remember to add that machine's IP here first — otherwise requests will fail with 403 Forbidden even with correct keys.
Iwapo unahamisha muunganisho wako kwenye seva mpya (au kuujaribu kutoka kifaa kingine, kama kifaa cha majaribio cha ndani), kumbuka kuongeza IP ya kifaa hicho hapa kwanza — vinginevyo maombi yatashindwa na 403 Forbidden hata kama funguo ni sahihi.
MerchantMfanyabiashara

Team accessUfikiaji wa timu

Invite colleagues to share access to your merchant dashboard without sharing a single login.

Karibisha wenzako kushiriki ufikiaji wa dashibodi yako bila kushiriki akaunti moja ya kuingia.

  • Invite a team member by email — they'll be able to sign in and view the dashboard for your business.
  • Suspend a team member's access at any time without deleting their history of actions.
  • API keys, IP whitelist entries, and settlement requests are scoped to the merchant account, not the individual user — any active team member can manage them.
  • Karibisha (Invite) mwanachama wa timu kwa barua pepe — ataweza kuingia na kuona dashibodi ya biashara yako.
  • Simamisha (Suspend) ufikiaji wa mwanachama wa timu wakati wowote bila kufuta historia yake ya matendo.
  • Funguo za API, orodha ya IP, na maombi ya kutoa fedha vinahusiana na akaunti ya mfanyabiashara, si mtumiaji binafsi — mwanachama wa timu yeyote aliye hai anaweza kuvisimamia.
MerchantMfanyabiashara

CollectionsMalipo yanayopokelewa

The Collections page lists every incoming mobile money payment created via the API, in the selected environment.

Ukurasa wa Collections unaorodhesha kila malipo ya pesa za simu yaliyoingia kupitia API, kwenye mazingira yaliyochaguliwa.

  • Filter by status and search by reference, customer name, or phone number.
  • Each row shows the gateway reference (yours to quote in support requests), your external_id, the customer's phone & provider, amount, fee, and status.
  • A failed collection shows the failure reason reported by AzamPay (e.g. customer cancelled, insufficient funds, timeout).
  • Chuja (Filter) kwa hali, na tafuta kwa kumbukumbu, jina la mteja, au namba ya simu.
  • Kila mstari unaonyesha kumbukumbu ya mfumo (gateway reference) (ya kutaja kwenye maombi ya msaada), external_id yako, simu & mtandao wa mteja, kiasi, ada, na hali.
  • Malipo yaliyoshindwa yanaonyesha sababu ya kushindwa kama ilivyoripotiwa na AzamPay (mfano, mteja alighairi, fedha hazitoshi, muda umeisha).
processing
USSD prompt sent, awaiting customer
success
Customer confirmed, balance credited
failed
Cancelled, expired, or declined
processing
Ombi la USSD limetumwa, linasubiri mteja
success
Mteja amethibitisha, salio limeongezwa
failed
Imeghairiwa, muda umeisha, au imekataliwa
MerchantMfanyabiashara

Settlements — "Toa Pesa"Kutoa fedha — "Toa Pesa"

From the Disbursements page, choose Request settlement to withdraw funds from your gateway balance directly to a mobile money account — no API integration required.

Kutoka ukurasa wa Disbursements, chagua Request settlement kutoa fedha kutoka salio lako moja kwa moja kwenda akaunti ya pesa za simu — bila kuhitaji muunganisho wa API.

FieldDescriptionMaelezo
Recipient name (Jina)RequiredInahitajikaName on the receiving mobile money account.Jina lililo kwenye akaunti ya pesa za simu inayopokea.
Payment network (Mtandao wa Malipo)RequiredInahitajikaAirtel, Tigo, Azampesa, Halopesa, or Mpesa.Airtel, Tigo, Azampesa, Halopesa, au Mpesa.
Amount (Kiasi cha Kutoa)RequiredInahitajikaMust not exceed your available balance.Haipaswi kuzidi salio lako linalopatikana.
Phone number (Namba ya Simu)RequiredInahitajikaTanzanian MSISDN, e.g. Namba ya simu ya Tanzania, mfano 0712345678.
RemarksOptionalSi lazimaFree-text note for your own records.Maelezo ya hiari kwa kumbukumbu zako.

Test modeHali ya Test

Settlement requests are simulated instantly — your balance is debited and the request shows as success right away, with no real payout sent.

Maombi ya kutoa fedha huigizwa papo hapo — salio lako linakatwa na ombi linaonyesha success mara moja, bila malipo halisi kutumwa.

Live modeHali ya Live

  1. The amount (plus platform fee) is held from your balance immediately when you submit the request.
  2. The request enters awaiting_approval and appears in the platform admin's approval queue.
  3. Once approved, AzamPay sends the payout and the request moves to success. If it's rejected or fails, the held amount is automatically refunded to your balance.
  1. Kiasi (pamoja na ada ya mfumo) kinatengwa kutoka salio lako mara moja unapotuma ombi.
  2. Ombi linaingia awaiting_approval na linaonekana kwenye orodha ya idhini ya msimamizi wa mfumo.
  3. Likithibitishwa, AzamPay hutuma malipo na ombi linabadilika kuwa success. Likikataliwa au kushindwa, kiasi kilichotengwa kinarejeshwa kiotomatiki kwenye salio lako.
Live settlements require KYC verification. If your account's KYC status isn't verified, the "Toa Pesa" button is disabled in Live mode — complete KYC from Settings first, or use Test mode to try the flow.
Kutoa fedha kwenye Live kunahitaji uthibitisho wa KYC. Iwapo hali ya KYC ya akaunti yako si verified, kitufe cha "Toa Pesa" kimezimwa kwenye Live — kamilisha KYC kwenye Settings kwanza, au tumia Test mode kujaribu mchakato.
IntegrationMuunganisho

Overview & authenticationMuhtasari & utambulisho

The Collections & Disbursements API lets your backend trigger mobile money checkout prompts (Tigo Pesa, Airtel Money, HaloPesa, AzamPesa) and send payouts, then track their status — either by polling or via webhooks.

Collections & Disbursements API inaruhusu backend yako kuanzisha maombi ya malipo ya pesa za simu (Tigo Pesa, Airtel Money, HaloPesa, AzamPesa) na kutuma fedha, kisha kufuatilia hali yake — kwa kuangalia (polling) au kupitia webhooks.

Authentication headersVichwa vya utambulisho

Every request to /api/v1/collections and /api/v1/disbursements must include the API key pair from API keys:

Kila ombi kwenda /api/v1/collections na /api/v1/disbursements linapaswa kujumuisha jozi ya funguo za API kutoka API keys:

Headers
X-Public-Key: gw_pk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-Secret-Key: gw_sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
Call this API only from your backend — never from a browser, mobile app, or any client the public can inspect. If a key pair is exposed, revoke it immediately from API keys and generate a new one.
Piga API hii kutoka backend yako tu — kamwe kutoka kwenye browser, app ya simu, au kifaa chochote kinachoweza kukaguliwa na umma. Iwapo jozi ya funguo imevuja, ifute mara moja kwenye API keys na utengeneze mpya.
IntegrationMuunganisho

Test vs. productionTest dhidi ya production

Every API key pair is tied to one environment. The environment is determined entirely by which key pair you send — there's no separate flag.

Kila jozi ya funguo za API inahusiana na mazingira moja tu. Mazingira huamuliwa kabisa na jozi ya funguo unayotumia — hakuna alama (flag) tofauti.

gw_pk_test_... / gw_sk_test_...
Collections & settlements are simulated instantly — no real USSD prompt, no real money. Perfect for development and demos.
gw_pk_production_... / gw_sk_production_...
Real money. Triggers an actual USSD prompt on the customer's phone and real AzamPay settlement.
gw_pk_test_... / gw_sk_test_...
Malipo & kutoa fedha huigizwa papo hapo — hakuna ombi halisi la USSD, hakuna fedha halisi. Inafaa kwa maendeleo na maonyesho.
gw_pk_production_... / gw_sk_production_...
Fedha halisi. Hutuma ombi halisi la USSD kwenye simu ya mteja na malipo halisi ya AzamPay.
Double-check which key pair you're using before testing against /api/v1/collections with a real phone number — production keys will send a live payment prompt.
Hakikisha jozi ya funguo unayotumia kabla ya kujaribu /api/v1/collections na namba halisi ya simu — funguo za production zitatuma ombi halisi la malipo.
IntegrationMuunganisho

Create a collectionKuunda malipo (collection)

Triggers a mobile money checkout prompt on the customer's phone. The customer confirms or cancels on their device; the final result arrives asynchronously (see Webhooks and status polling).

Hutuma ombi la malipo ya pesa za simu kwenye simu ya mteja. Mteja anathibitisha au anaghairi kwenye kifaa chake; jibu la mwisho hufika kwa njia ya asynchronous (tazama Webhooks na kuangalia hali).

POST /api/v1/collections X-Public-Key / X-Secret-Key

Request bodyMaudhui ya ombi

FieldTypeDescriptionMaelezo
account_numberstringRequiredInahitajikaCustomer's mobile money number, e.g. Namba ya pesa za simu ya mteja, mfano 0712345678.
amountnumberRequiredInahitajikaAmount to collect (whole units, e.g. TZS).Kiasi cha kupokea (namba kamili, mfano TZS).
currencystringOptionalSi lazimaDefaults to Hutumia chaguo-msingi TZS.
providerstringRequiredInahitajikaTigo, Airtel, Halopesa, Azampesa, or Mpesa — must match the customer's network.Tigo, Airtel, Halopesa, Azampesa, au Mpesa — lazima ilingane na mtandao wa mteja.
external_idstringRequiredInahitajikaYour own unique reference for this payment (max 30 chars). Used to reconcile against your records.Kumbukumbu yako ya kipekee kwa malipo haya (herufi 30 kiwango cha juu). Hutumika kulinganisha na kumbukumbu zako.
customer_namestringOptionalSi lazimaCustomer's name, for your records and receipts.Jina la mteja, kwa kumbukumbu na risiti zako.

Example requestMfano wa ombi

bash — cURL
curl -X POST https://your-gateway-domain/api/v1/collections \
  -H "X-Public-Key: gw_pk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-Secret-Key: gw_sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "account_number": "0712345678",
    "amount": 1000,
    "currency": "TZS",
    "provider": "Tigo",
    "external_id": "INV-00123",
    "customer_name": "Asha Mwakasege"
  }'
PHP — cURL
$ch = curl_init('https://your-gateway-domain/api/v1/collections');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'X-Public-Key: gw_pk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
        'X-Secret-Key: gw_sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'account_number' => '0712345678',
        'amount'         => 1000,
        'currency'       => 'TZS',
        'provider'       => 'Tigo',
        'external_id'    => 'INV-00123',
        'customer_name'  => 'Asha Mwakasege',
    ]),
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

// Save $response['data']['uuid'] - you'll need it to check status.

Example response — 201 CreatedMfano wa jibu — 201 Created

json
{
  "success": true,
  "message": "Checkout request sent to customer (test mode - simulated)",
  "data": {
    "uuid": "c4497523-a565-4766-a03d-441b045dc1e8",
    "reference": "col_vg5mOoA4QIJoxJK9MfhTLQ",
    "status": "processing",
    "amount": 1000,
    "currency": "TZS",
    "provider": "Tigo",
    "external_id": "INV-00123"
  }
}
  • uuid — the gateway's internal identifier. Store this to poll status.
  • reference — a human-friendly gateway reference (also shown in the dashboard ledger).
  • status — always processing immediately after creation; the customer hasn't responded yet.
  • uuid — kitambulisho cha ndani cha mfumo. Kihifadhi ili kuangalia hali baadaye.
  • reference — kumbukumbu rahisi ya mfumo (huonekana pia kwenye kumbukumbu za dashibodi).
  • status — huwa processing mara baada ya kuundwa; mteja hajajibu bado.
IntegrationMuunganisho

Check collection statusKuangalia hali ya malipo

Poll this endpoint to find out whether the customer confirmed or cancelled the prompt. For most integrations, webhooks are faster — use polling as a fallback or for an on-demand "refresh" button.

Angalia (poll) njia hii kujua kama mteja alithibitisha au kughairi ombi. Kwa muunganisho mwingi, webhooks ni za haraka zaidi — tumia polling kama njia mbadala au kwa kitufe cha "refresh".

GET /api/v1/collections/{uuid}/status X-Public-Key / X-Secret-Key

Example requestMfano wa ombi

bash — cURL
curl -X GET "https://your-gateway-domain/api/v1/collections/c4497523-a565-4766-a03d-441b045dc1e8/status" \
  -H "X-Public-Key: gw_pk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-Secret-Key: gw_sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Example response — 200 OKMfano wa jibu — 200 OK

json
{
  "success": true,
  "data": {
    "uuid": "c4497523-a565-4766-a03d-441b045dc1e8",
    "reference": "col_vg5mOoA4QIJoxJK9MfhTLQ",
    "status": "success",
    "amount": 1000,
    "currency": "TZS",
    "provider": "Tigo",
    "external_id": "INV-00123",
    "created_at": "2026-06-13T22:31:35Z",
    "updated_at": "2026-06-13T22:31:42Z"
  }
}

Possible status valuesHali zinazowezekana

processing
Awaiting customer response
success
Payment confirmed & balance credited
failed
Cancelled, declined, or expired
processing
Linasubiri jibu la mteja
success
Malipo yamethibitishwa & salio limeongezwa
failed
Imeghairiwa, imekataliwa, au muda umeisha
A collection can stay processing for up to a few minutes if the customer hasn't actioned the prompt. If your integration needs a hard cutoff, treat anything still processing after ~5 minutes as likely abandoned, while still honoring a late success if it arrives.
Malipo yanaweza kubaki processing kwa dakika kadhaa iwapo mteja hajajibu ombi. Iwapo muunganisho wako unahitaji kikomo, chukulia kitu chochote kilichobaki processing baada ya dakika ~5 kama kimeshindikana, huku ukikubali success ya kuchelewa ikiwasili baadaye.
IntegrationMuunganisho

Disbursements APIAPI ya kutoa fedha

Send a payout from your gateway balance to a mobile money account — the API equivalent of the dashboard's "Toa Pesa" settlement flow.

Tuma malipo kutoka salio lako kwenda akaunti ya pesa za simu — sawa na mchakato wa "Toa Pesa" kwenye dashibodi, lakini kupitia API.

POST /api/v1/disbursements X-Public-Key / X-Secret-Key

Request bodyMaudhui ya ombi

FieldTypeDescriptionMaelezo
account_numberstringRequiredInahitajikaRecipient's mobile money number.Namba ya pesa za simu ya mpokeaji.
amountnumberRequiredInahitajikaBetween 1 and 5,000,000.Kati ya 1 na 5,000,000.
providerstringRequiredInahitajikaAirtel, Tigo, Azampesa, Halopesa, or au Mpesa.
external_idstringRequiredInahitajikaYour unique reference (max 30 chars).Kumbukumbu yako ya kipekee (herufi 30 kiwango cha juu).
recipient_namestringOptionalSi lazimaName on the receiving account.Jina lililo kwenye akaunti inayopokea.
remarksstringOptionalSi lazimaFree-text note.Maelezo ya hiari.

Example requestMfano wa ombi

bash — cURL
curl -X POST https://your-gateway-domain/api/v1/disbursements \
  -H "X-Public-Key: gw_pk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-Secret-Key: gw_sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "account_number": "0712345678",
    "amount": 5000,
    "provider": "Tigo",
    "external_id": "PAYOUT-00045",
    "recipient_name": "Juma Hassan",
    "remarks": "Agent commission"
  }'

Example responseMfano wa jibu

json — test mode (instant)
{
  "success": true,
  "message": "Disbursement processed (test mode - simulated)",
  "data": {
    "uuid": "2d669155-b63e-4461-97c5-c2cb2431a8e8",
    "reference": "dsb_Oty4AbTnH1AprpsIHQAJA",
    "status": "success",
    "amount": 5000,
    "provider": "Tigo",
    "external_id": "PAYOUT-00045"
  }
}
json — production (202 Accepted)
{
  "success": true,
  "message": "Disbursement request received and is awaiting approval.",
  "data": {
    "uuid": "acbd3bd7-22f8-491c-81b3-41dd3cd902dd",
    "reference": "dsb_6LEnBEbXjVZ58BqS6QaDPw",
    "status": "awaiting_approval",
    "amount": 5000,
    "provider": "Tigo",
    "external_id": "PAYOUT-00045"
  }
}
In production, the amount + fee is held from your balance immediately and the request waits for platform admin approval — see Settlement & disbursement approvals. Poll status the same way as collections, via GET /api/v1/disbursements/{reference}/status.
Kwenye production, kiasi + ada hutengwa kutoka salio lako mara moja na ombi linasubiri idhini ya msimamizi wa mfumo — tazama Uthibitisho wa kutoa fedha. Angalia hali kwa njia sawa na malipo, kupitia GET /api/v1/disbursements/{reference}/status.

Check disbursement statusKuangalia hali ya kutoa fedha

GET /api/v1/disbursements/{reference}/status X-Public-Key / X-Secret-Key
awaiting_approval
Held, queued for admin review
success
Sent to recipient
failed
Send failed, balance refunded
rejected
Declined by admin, balance refunded
awaiting_approval
Imetengwa, inasubiri ukaguzi wa msimamizi
success
Imetumwa kwa mpokeaji
failed
Imeshindwa kutumwa, salio limerejeshwa
rejected
Imekataliwa na msimamizi, salio limerejeshwa
IntegrationMuunganisho

WebhooksWebhooks (arifa)

If you configure a webhook URL in Settings, the gateway sends a signed POST request to it whenever a collection resolves — this is the fastest way to know a payment succeeded, without polling.

Iwapo umeweka webhook URL kwenye Settings, mfumo hutuma ombi la POST lililosainiwa kila malipo yanapokamilika — hii ni njia ya haraka zaidi ya kujua malipo yamefanikiwa, bila polling.

SetupUsanidi

  1. In your merchant Settings, set your Webhook URL — an HTTPS endpoint on your server that accepts POST requests.
  2. Note your callback secret, shown alongside the webhook URL — you'll use it to verify the signature on every delivery.
  1. Kwenye Settings ya mfanyabiashara, weka Webhook URL yako — njia ya HTTPS kwenye seva yako inayopokea maombi ya POST.
  2. Hifadhi callback secret yako, inayoonyeshwa kando ya webhook URL — utaitumia kuhakiki sahihi (signature) kwa kila ujumbe.

PayloadMaudhui (Payload)

json — collection.success
{
  "event": "collection.success",
  "data": {
    "reference": "col_vg5mOoA4QIJoxJK9MfhTLQ",
    "uuid": "c4497523-a565-4766-a03d-441b045dc1e8",
    "status": "success",
    "amount": 1000,
    "currency": "TZS",
    "external_id": "INV-00123"
  }
}

A failed collection sends event: "collection.failed" with data.status: "failed", using the same shape.

Malipo yaliyoshindwa hutuma event: "collection.failed" na data.status: "failed", kwa muundo ule mmoja.

Verifying the signatureKuhakiki sahihi (signature)

Every delivery includes an X-Signature header — an HMAC-SHA256 of the raw request body, signed with your callback secret. Always verify it before trusting the payload.

Kila ujumbe una kichwa cha X-Signature — HMAC-SHA256 ya maudhui ghafi ya ombi, iliyosainiwa na callback secret yako. Hakiki kila wakati kabla ya kuamini maudhui.

PHP
$rawBody = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_SIGNATURE'] ?? '';
$callbackSecret = 'your-callback-secret-from-settings';

$expected = hash_hmac('sha256', $rawBody, $callbackSecret);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

$event = json_decode($rawBody, true);

if ($event['event'] === 'collection.success') {
    // Mark the order matching $event['data']['external_id'] as paid.
}

http_response_code(200);
echo json_encode(['received' => true]);
Respond with a 2xx status quickly (ideally under a few seconds). If your endpoint is slow or unreachable, the gateway logs the delivery attempt but does not currently retry — use status polling as a backstop for critical flows.
Jibu kwa hali ya 2xx haraka (ikiwezekana ndani ya sekunde chache). Iwapo njia yako ni ya polepole au haifikiki, mfumo huhifadhi kumbukumbu ya jaribio lakini hauiretumi kwa sasa — tumia status polling kama hifadhi ya ziada kwa mchakato muhimu.
IntegrationMuunganisho

Status & error codesMisimbo ya hali & makosa

Every response includes a top-level success boolean and a human-readable message. Errors follow the same shape:

Kila jibu lina success (kweli/sivyo) na message inayosomeka. Makosa hutumia muundo ule mmoja:

json — error shape
{
  "success": false,
  "message": "Insufficient balance"
}
HTTP statusMeaningCommon causes
200 / 201 / 202SuccessRequest accepted & processed (202 = queued for approval).
400Bad requestMissing/invalid field — e.g. invalid phone number, unsupported provider, external_id too long, malformed JSON.
401UnauthorizedMissing or invalid X-Public-Key / X-Secret-Key.
402Payment requiredInsufficient balance for a disbursement / settlement.
403ForbiddenRequest IP not in your IP whitelist, or KYC required for a production settlement.
404Not foundUnknown collection/disbursement UUID for this merchant.
405Method not allowedWrong HTTP verb for the endpoint.
500Server errorUnexpected internal error — retry, and contact support if it persists.
Hali ya HTTPMaanaSababu za kawaida
200 / 201 / 202ImefanikiwaOmbi limepokelewa & kuchakatwa (202 = linasubiri idhini).
400Ombi batiliSehemu inayokosekana/batili — mfano namba ya simu batili, provider isiyotambulika, external_id ndefu kupita kiasi, JSON yenye makosa.
401HauruhusiwiX-Public-Key / X-Secret-Key hazipo au si sahihi.
402Malipo yanahitajikaSalio halitoshi kwa kutoa fedha / settlement.
403ImekatazwaIP ya ombi haipo kwenye IP whitelist yako, au KYC inahitajika kwa settlement ya production.
404HaipoUUID ya malipo/kutoa fedha haijulikani kwa mfanyabiashara huyu.
405Njia hairuhusiwiAina ya ombi (HTTP verb) si sahihi kwa njia hiyo.
500Kosa la sevaKosa la ndani lisilotarajiwa — jaribu tena, na wasiliana na msaada iwapo litarudia.

Validation messages you may seeUjumbe wa uhakiki unaoweza kuonekana

  • "external_id is required" / "external_id must be 30 characters or fewer"
  • "amount must be between 1 and 5,000,000"
  • "provider must be one of: Airtel, Tigo, Azampesa, Halopesa, Mpesa" (disbursements)(kutoa fedha)
  • "account_number must be a valid Tanzanian phone number"
  • "Insufficient balance"
  • "Production settlements require KYC verification. Please complete KYC first."
IntegrationMuunganisho

Test consoleKifaa cha majaribio

Use the Collections API Test Console to send real requests against the gateway from your browser — without writing any code — and see the raw JSON response, status, and timing for each call.

Tumia Collections API Test Console kutuma maombi halisi kwa mfumo kutoka kwenye browser yako — bila kuandika msimbo wowote — na kuona jibu la JSON, hali, na muda wa kila ombi.

Open the live Collections Test Console Fungua Kifaa cha Majaribio cha Collections (live) dalipay.co.tz/collection.php
  1. Open the live test console linked above, or run your own copy: open collections_test.php (place it anywhere PHP runs, e.g. php -S 0.0.0.0:8090 collections_test.php).
  2. Enter your gateway's Base URL (e.g. http://your-domain/api/v1) and your X-Public-Key / X-Secret-Key from API keys.
  3. Step 1 — Create a collection: fill in a phone number, amount, and provider, then send. Use a test key pair first to confirm everything is wired up before trying production.
  4. Step 2 — Check status: the UUID from a successful create auto-fills here — click "Check status" to poll the result.
  1. Fungua kifaa cha majaribio cha live kilichounganishwa hapo juu, au tumia nakala yako: fungua collections_test.php (weka popote PHP inafanya kazi, mfano php -S 0.0.0.0:8090 collections_test.php).
  2. Weka Base URL ya mfumo wako (mfano http://your-domain/api/v1) na X-Public-Key / X-Secret-Key kutoka API keys.
  3. Hatua ya 1 — Kuunda malipo: jaza namba ya simu, kiasi, na mtandao, kisha tuma. Tumia jozi ya funguo za test kwanza kuhakiki kila kitu kinafanya kazi kabla ya production.
  4. Hatua ya 2 — Kuangalia hali: UUID kutoka kwenye ombi lililofanikiwa itajazwa hapa kiotomatiki — bonyeza "Check status" kuangalia matokeo.
This console runs entirely server-side via cURL, so it works from any server that can reach your gateway. If you run it on a different machine than the gateway, make sure that machine's IP is in your IP whitelist (if configured), and that the gateway's port/domain is reachable from it.
Kifaa hiki kinafanya kazi kwa kutumia cURL kwenye seva, hivyo kinafanya kazi kutoka seva yoyote inayoweza kufikia mfumo wako. Iwapo unakitumia kwenye kifaa tofauti na mfumo, hakikisha IP ya kifaa hicho ipo kwenye IP whitelist yako (iwapo imewekwa), na kwamba port/domain ya mfumo inafikika kutoka huko.
Using production keys in the test console sends a real USSD prompt to the phone number you enter. Double-check the key pair and phone number before clicking "Send collection request" in Live mode.
Kutumia funguo za production kwenye kifaa cha majaribio hutuma ombi halisi la USSD kwenye namba ya simu unayoweka. Hakikisha jozi ya funguo na namba ya simu kabla ya kubonyeza "Send collection request" kwenye Live mode.