M-Pesa — Encyclopedia
Last updated: January 2024
Overview
Section titled “Overview”M-Pesa is the world’s most successful mobile money service. Launched by Safaricom in Kenya in 2007, it transformed how East Africa transacts and became the template for mobile money globally. It is operated by Safaricom in Kenya, with M-Pesa Africa (a Safaricom/Vodacom joint venture) licensing the brand across other African markets.
Understanding M-Pesa is essential for any developer building payment integrations for Kenya. For many Kenyans, M-Pesa is money — it’s where salaries arrive, bills are paid, and savings are kept.
Ownership & Structure
Section titled “Ownership & Structure”| Detail | Value |
|---|---|
| Operator | Safaricom PLC (Kenya) |
| Ownership | Vodacom Group (35%), Kenyan government and public (65%) |
| Founded | 2007 |
| Regulator | Central Bank of Kenya (CBK) |
| License | Non-Bank Payment Service Provider (CBK) |
| Active Users | ~32 million (Kenya, as of 2023) |
| Annual Transactions | ~$314 billion USD processed (2023) |
M-Pesa processes roughly 50% of Kenya’s GDP in transaction value annually. This is not a payment method — it is national financial infrastructure.
Market Position
Section titled “Market Position”M-Pesa’s position in Kenya is more dominant than Telebirr in Ethiopia. Kenya has a competitive mobile network market (Safaricom, Airtel, Telkom), yet M-Pesa maintains overwhelming market share because:
- It was first (2007, a decade before competitors)
- Network effects: everyone already has M-Pesa
- Deep integration into daily life (salaries, utilities, government services, e-commerce)
- M-Pesa agents exist even in rural Kenya — physical cash-in/cash-out infrastructure
Competitors (Airtel Money, Equitel) exist but have low adoption.
How M-Pesa Works for Merchants
Section titled “How M-Pesa Works for Merchants”Lipa Na M-Pesa (Pay by M-Pesa)
Section titled “Lipa Na M-Pesa (Pay by M-Pesa)”The primary merchant payment product. Two variants:
1. STK Push (Recommended for online merchants)
- Your system sends a payment request via Safaricom API
- Customer receives a USSD push on their phone
- Customer enters M-Pesa PIN to approve
- Callback sent to your system
2. PayBill / Buy Goods
- Customer initiates payment by entering your PayBill number on their phone
- Used for in-person or manual payments
- Not suitable for automated online checkout
For online integrations, STK Push is what you want — and what Zirzir uses under the hood.
Credentials & Developer Access
Section titled “Credentials & Developer Access”M-Pesa’s developer ecosystem is more mature than Ethiopian gateways. Safaricom runs the Daraja API platform (Daraja means “bridge” in Swahili).
To get credentials:
- Register at developer.safaricom.co.ke
- Create an app — sandbox credentials are immediate
- For production: apply for Go Live, provide business documentation
- Go Live review typically takes 1-2 weeks
| Credential | Description |
|---|---|
consumerKey | Your app’s consumer key |
consumerSecret | Your app’s consumer secret |
businessShortCode | Your PayBill or Till number |
passKey | Lipa Na M-Pesa passkey (provided after approval) |
callbackUrl | Webhook URL for STK Push results |
Fee Structure
Section titled “Fee Structure”Merchant Fees (Lipa Na M-Pesa)
Section titled “Merchant Fees (Lipa Na M-Pesa)”M-Pesa’s merchant fee structure depends on your agreement type:
Buy Goods (Till Number)
| Transaction Amount (KES) | Fee |
|---|---|
| 1 - 100 | 0 KES |
| 101 - 500 | 7 KES |
| 501 - 1,000 | 13 KES |
| 1,001 - 1,500 | 23 KES |
| 1,501 - 2,500 | 33 KES |
| 2,501 - 3,500 | 53 KES |
| 3,501 - 5,000 | 57 KES |
| 5,001 - 7,500 | 78 KES |
| 7,501 - 10,000 | 90 KES |
| 10,001 - 15,000 | 100 KES |
| 15,001 - 20,000 | 105 KES |
PayBill (Business Number) PayBill fees vary by industry and are negotiated with Safaricom. Banks, utility companies, and large merchants typically have custom rates.
Fee Negotiation
Section titled “Fee Negotiation”Merchants above ~KES 5 million/month in volume have room to negotiate. Contact your Safaricom Enterprise account manager.
Settlement
Section titled “Settlement”| Detail | Value |
|---|---|
| Advertised cycle | T+1 business days |
| Real-world cycle | T+1 (more reliable than Ethiopian gateways) |
| Settlement currency | KES |
| Settlement method | Bank transfer to registered business account |
| Settlement days | Monday - Friday |
| Reporting | Via M-Pesa portal or API |
M-Pesa’s settlement is more reliable and consistent than most African payment gateways. T+1 is generally what you actually get.
Daraja API — Quality Assessment
Section titled “Daraja API — Quality Assessment”Safaricom’s Daraja platform is the most mature payment API in sub-Saharan Africa.
| Aspect | Rating | Notes |
|---|---|---|
| API documentation | 4/5 | Good, with some outdated sections |
| Sandbox | 4/5 | Solid; simulates STK Push without real phone |
| Production stability | 5/5 | Excellent, enterprise-grade uptime |
| Error messages | 3/5 | Improving but still occasionally cryptic |
| Support | 3/5 | Developer forums active; enterprise support better |
| OAuth token handling | 3/5 | Tokens expire every hour — must be managed |
Daraja quirks:
- OAuth tokens expire every 3600 seconds. Zirzir handles refresh automatically
- STK Push callbacks sometimes arrive out of order — always verify via API, not just callbacks
- Production and sandbox use different base URLs and different credentials — easy to mix up
- The
ResultCode: 0means success, but always checkResultDesctoo - Phone numbers must be in
2547XXXXXXXXformat (country code, no+)
Regulation
Section titled “Regulation”M-Pesa operates under:
- Central Bank of Kenya National Payment System Act (2011)
- CBK National Payment System Regulations (2014)
- CBK Prudential Guidelines for Digital Credit Providers (2022)
Safaricom holds a Payment Service Provider license from CBK. As a Daraja API user, you are operating under Safaricom’s license — you don’t need your own CBK payment license to process M-Pesa payments. However, depending on your business model, you may need other CBK registrations.
M-Pesa Across Africa
Section titled “M-Pesa Across Africa”The M-Pesa brand operates in multiple African countries through M-Pesa Africa, a Safaricom/Vodacom joint venture. Each country is a separate API, separate credentials, and different features:
| Country | Operator | API Platform | Notes |
|---|---|---|---|
| Kenya | Safaricom | Daraja | Most mature |
| Tanzania | Vodacom | M-Pesa OpenAPI | Different API, same brand |
| DRC | Vodacom | M-Pesa OpenAPI | |
| Mozambique | Vodacom | M-Pesa OpenAPI | |
| Ghana | Vodafone | M-Pesa OpenAPI | |
| Ethiopia | Safaricom Ethiopia | Limited | New market, limited reach |
Important: M-Pesa Kenya and M-Pesa Tanzania are different products with different APIs. Do not assume your Kenya integration will transfer.
Common Integration Issues
Section titled “Common Integration Issues””STK Push callback not received”
Section titled “”STK Push callback not received””The most common issue. Causes:
callbackUrlis not publicly accessible (localhost won’t work in production)- Firewall blocking Safaricom’s callback IP ranges
- HTTPS required — Safaricom won’t call HTTP endpoints in production
- URL must respond within 5 seconds or Safaricom marks it as failed
”Invalid Access Token”
Section titled “”Invalid Access Token””Tokens expire every 3600 seconds. Ensure you’re refreshing proactively, not reactively.
”The transaction amount is less than the minimum amount”
Section titled “”The transaction amount is less than the minimum amount””Minimum STK Push transaction: 1 KES. But some operations have higher minimums — check the specific endpoint docs.
”Request cancelled by user”
Section titled “”Request cancelled by user””Customer dismissed the USSD prompt. The transaction is permanently failed — you cannot re-push the same request.
Useful Links
Section titled “Useful Links”- Daraja developer portal: developer.safaricom.co.ke
- API documentation: developer.safaricom.co.ke/docs
- Developer forum: developer.safaricom.co.ke/forum
- Status page: safaricom.co.ke/service-status
- Enterprise sales: [email protected]