Telebirr — Encyclopedia
Last updated: January 2024
Overview
Section titled “Overview”Telebirr is the mobile money service operated by Ethio Telecom, the state-owned telecommunications monopoly of Ethiopia. Launched in May 2021, it became the fastest-growing mobile money service in African history by user count, reaching 40 million registered users within two years.
It is the most important payment rail in Ethiopia by volume — for many Ethiopians, especially outside Addis Ababa, Telebirr is the only accessible digital payment method.
Ownership & Structure
Section titled “Ownership & Structure”| Detail | Value |
|---|---|
| Operator | Ethio Telecom |
| Ownership | Ethiopian government (100% state-owned) |
| Regulator | National Bank of Ethiopia (NBE) |
| Technology Partner | Huawei (infrastructure) |
| Launch Date | May 2021 |
| Registered Users | ~40 million (as of end 2023) |
| Monthly Active Users | ~18 million (estimated) |
Ethio Telecom’s state ownership has significant practical implications: decisions move slowly, merchant onboarding is bureaucratic, and API stability is sometimes deprioritized relative to consumer features. On the upside, it’s deeply embedded in government payment flows — if you’re building anything that touches government services, Telebirr is mandatory.
Market Position
Section titled “Market Position”Telebirr is not just dominant — it’s structurally dominant. Ethio Telecom controls the only major mobile network in Ethiopia (Safaricom and others have entered but with limited reach), meaning that virtually every mobile money user in Ethiopia is already on Telebirr infrastructure.
This changed somewhat with Safaricom Ethiopia’s entry in 2022 and M-Pesa Ethiopia’s launch, but Telebirr maintains overwhelming market share as of 2024.
How the Payment Network Works
Section titled “How the Payment Network Works”For Consumers
Section titled “For Consumers”- Consumers register via USSD (
*127#) or the Telebirr app - Wallets are funded via cash at Ethio Telecom service centers, authorized agents, or bank transfers
- Wallet limit: 50,000 ETB stored value, 100,000 ETB monthly transaction limit for verified accounts
- Unverified accounts: 5,000 ETB limit
For Merchants
Section titled “For Merchants”- Merchants register via the Ethio Telecom business center or merchant portal
- Payments are received via USSD push to customer phones
- Merchant wallets are separate from consumer wallets
- Settlement to bank account on T+1 business day cycle
USSD Infrastructure
Section titled “USSD Infrastructure”Telebirr is fundamentally a USSD service. Even the smartphone app is largely a wrapper around USSD flows. This has practical implications:
- Payments work without smartphones or data
- Works on the most basic feature phones
- USSD sessions can time out under poor network conditions
- The 5-minute payment window is a hard system limit, not a suggestion
Fee Structure
Section titled “Fee Structure”Fees are set by Ethio Telecom and subject to change. The National Bank of Ethiopia reviews and approves the fee schedule. Verify current rates via your merchant agreement.
Merchant Fees (Receiving Money)
Section titled “Merchant Fees (Receiving Money)”| Transaction Amount | Fee Rate |
|---|---|
| 1 - 500 ETB | 0.8% |
| 501 - 10,000 ETB | 0.8% |
| 10,001+ ETB | 0.8% |
| Minimum fee | 1 ETB |
| Maximum fee | 100 ETB |
Fees are deducted from merchant settlements, not charged to the customer at point of payment.
Consumer Transfer Fees (P2P)
Section titled “Consumer Transfer Fees (P2P)”These don’t affect merchant integrations but are useful context:
| Amount | Fee |
|---|---|
| 1 - 100 ETB | Free |
| 101 - 500 ETB | 2 ETB |
| 501 - 1,000 ETB | 3 ETB |
| 1,001 - 5,000 ETB | 5 ETB |
| 5,001 - 10,000 ETB | 7 ETB |
Fee Negotiation
Section titled “Fee Negotiation”Merchants processing above ~500,000 ETB/month have had success negotiating reduced rates through their Ethio Telecom account manager. There’s no published tier structure for this — it’s relationship-based.
Settlement
Section titled “Settlement”| Detail | Value |
|---|---|
| Advertised cycle | T+1 business days |
| Real-world cycle | T+1 to T+2 |
| Settlement days | Monday - Friday (no weekend settlements) |
| Minimum settlement | 100 ETB |
| Settlement currency | ETB only |
| Settlement method | Bank transfer to registered merchant bank account |
What T+1 actually means: If a customer pays on Monday, you receive funds Tuesday — if the batch runs before cutoff. Transactions after ~3 PM Ethiopian time often roll to the next day’s batch, effectively becoming T+2.
Holidays extend this significantly. During major Ethiopian holidays (Ethiopian Christmas/Gena, Timkat, Ethiopian Easter/Fasika, Eid), batches may pause for 2-3 days.
Merchant Onboarding
Section titled “Merchant Onboarding”This is the painful part. As of early 2024, the process involves:
- Visit an Ethio Telecom business center (Addis Ababa has several; major cities have one)
- Submit documentation:
- Trade license (business license from Ministry of Trade)
- TIN (Tax Identification Number)
- Business bank account details
- Authorized signatory ID
- Wait for review — typically 1-3 weeks
- Receive merchant credentials — App ID, App Key, short code
- Request sandbox access separately — this is a different process and can take additional days
There is no fully online onboarding as of 2024. You must appear in person or designate an authorized representative.
Pro tip: The Bole Road business center in Addis is the most experienced with merchant accounts. Going to a smaller branch often results in being told to come back or visit a different location.
API Quality & Stability
Section titled “API Quality & Stability”Honest assessment: mixed.
| Aspect | Rating | Notes |
|---|---|---|
| API documentation | 2/5 | Exists, often outdated or incomplete |
| Sandbox reliability | 2/5 | Doesn’t simulate USSD; auto-succeeds transactions |
| Production stability | 3/5 | Generally stable with occasional outages |
| Error messages | 2/5 | Vague; often requires trial and error |
| Support responsiveness | 2/5 | Varies heavily by account manager |
| Webhook reliability | 3/5 | Works, but no retry mechanism on their side |
Common API issues developers encounter:
- Auth token format changed in late 2022 without notice
- Certain error codes return HTTP 200 with a failure body — always check the response body, not just the status code
- RSA encryption required for certain endpoints; the public key format in docs is sometimes wrong
- Sandbox does not validate phone numbers — production does
Regulation
Section titled “Regulation”Telebirr operates under:
- National Bank of Ethiopia Payment Instrument Issuers Directive (FIS/01/2012 and subsequent updates)
- Mobile and Agent Banking Directives (SBB/57/2018)
- National Payment System Proclamation (948/2016)
The NBE sets maximum transaction limits, fee approval requirements, and KYC standards. Ethio Telecom’s state ownership means regulatory approval is typically smooth — but also means that regulatory changes at NBE directly affect Telebirr operations.
For merchants processing above 1 million ETB/month, additional NBE reporting requirements may apply. Consult your legal team.
Common Integration Issues
Section titled “Common Integration Issues””Transaction succeeded but we never got the webhook”
Section titled “”Transaction succeeded but we never got the webhook””Telebirr’s webhook system does not retry on failure. If your endpoint was down or returned an error, the webhook is gone. Implement verify() polling as a fallback.
”Customer says they paid but status is pending”
Section titled “”Customer says they paid but status is pending””- Check if the 5-minute USSD window expired
- Verify the phone number was Ethio Telecom (not a non-Telebirr number)
- Check the Telebirr merchant portal — sometimes the transaction succeeded on their end but the webhook never fired
”Auth errors after credentials worked previously”
Section titled “”Auth errors after credentials worked previously””Telebirr access tokens expire every 30 minutes. If you’re managing tokens manually (not using the Zirzir SDK), ensure you’re refreshing. Also check: RSA public key used for token generation sometimes changes without notice.
”Sandbox transactions always succeed immediately”
Section titled “”Sandbox transactions always succeed immediately””Correct. Telebirr sandbox doesn’t simulate actual USSD. All transactions complete automatically after ~30 seconds. Do not rely on sandbox for realistic flow testing.
Contacts
Section titled “Contacts”- Merchant support line: +251 990 (Ethio Telecom customer service)
- Business center (Bole Road, Addis Ababa): Best for merchant issues
- Developer portal: developer.ethiotelecom.et (access may require a merchant account)
For API issues, your Ethio Telecom account manager is the primary escalation path. There is no public developer support forum.