Mobile Money Collections

Send a USSD payment prompt to a customer’s phone. They approve with their PIN and the funds transfer instantly. Supports M-Pesa (Vodacom), Airtel Money, Mixx by Yas, and HaloPesa.

How it works

Your server calls POST /api/v1/payments/collection
Stakaba sends a USSD prompt to the customer’s phone
The customer enters their mobile money PIN to approve
Stakaba sends a webhook when payment is confirmed

Collect a payment

POST /api/v1/payments/collection
x-api-key: sk_live_...
Content-Type: application/json

{
  "grossAmount": 5000,
  "currency": "TZS",
  "mobileNumber": "255742000331",
  "network": "Mpesa",
  "metadata": {
    "orderId": "ORD-2026-001"
  }
}

Response:

{
  "internalReference": "M_X7Y8Z9W0"
}

The customer will receive a USSD prompt on their phone within seconds.

Parameters

Field	Type	Required	Description
`grossAmount`	integer	Yes	Amount in TZS — must be a whole number
`currency`	string	No	Always `TZS`
`mobileNumber`	string	Yes	Recipient number in `255XXXXXXXXX` format
`network`	string	Yes	See supported networks below
`metadata`	object	No	Your custom data, returned in webhooks

Supported networks

`network` value	Operator
`Mpesa`	Vodacom M-Pesa
`AirtelMoney`	Airtel Money
`TigoPesa`	Mixx by Yas (Tigo)
`HaloPesa`	HaloPesa

The network value is case-sensitive. Use exactly the values shown above.

Amount requirements

grossAmount must be a whole integer — mobile money operators do not accept decimal amounts.

{ "grossAmount": 5000 }   // ✓ correct
{ "grossAmount": 4999.50 }  // ✗ rejected

Check payment status

GET /api/v1/transactions/M_X7Y8Z9W0
x-api-key: sk_live_...

Or receive real-time updates via webhook.