Telebirr Payment Gateway Integration Guide: 2026 Developer & Merchant Manual
Complete Telebirr payment gateway integration guide for Ethiopian websites, e-commerce, and mobile apps. SuperApp, H5 web checkout, and API setup.
Integrating Telebirr into Ethiopian websites, e-commerce stores, and mobile apps enables automated digital checkout for over 45 million mobile money users. Integration is accomplished through Ethio Telecom Telebirr Developer Portal via H5 Web Pay, In-App SDK, or Mini-App integration. Key technical requirements include RSA cryptographic key exchange, webhook listener verification, and automated transaction reconciliation.
Last reviewed
Award-Winning Technology Partner
Winner: Best Enterprise Software & Web Development Agency (East Africa Digital Excellence Awards 2025)
Why Telebirr Integration is Essential for Ethiopian Digital Commerce
With over 45 million registered subscribers across Ethiopia, Telebirr has become the undisputed backbone of mobile financial transactions in the country. For any business operating a website, online store, mobile application, or ERP system, accepting Telebirr is no longer an optional feature. It is a fundamental requirement for commercial survival.
Relying on manual bank transfer screenshots sent over Telegram creates severe operational bottlenecks, delays order fulfillment, and exposes businesses to fraudulent receipt manipulation. An automated Telebirr gateway integration validates payments in real time, generates instant customer receipts, and triggers automated order processing with zero human intervention.
Telebirr Integration Modes for Ethiopian Businesses
| Integration Mode | Technical Architecture | Best Use Case | User Experience Flow |
|---|---|---|---|
| Telebirr H5 Web Pay | Server-to-server API request generating a secure mobile-optimized payment URL or QR code. | E-commerce websites, WooCommerce, Shopify, custom web portals. | Customer selects Telebirr at checkout, enters mobile number or scans QR code, confirms with PIN, and redirects back with order confirmation. |
| Telebirr In-App SDK | Native Android/iOS or Flutter SDK embedded directly inside your mobile application. | Custom mobile applications (ride-hailing, food delivery, ticketing). | Direct app-to-app switch to Telebirr app for instantaneous biometric or PIN authorization, returning immediately to your app. |
| Telebirr SuperApp Mini-Program | Lightweight web application hosted directly inside the official Telebirr SuperApp ecosystem. | Consumer services targeting the entire 45M+ Telebirr user base without requiring separate app downloads. | Instant access inside Telebirr with pre-authenticated user profile and frictionless native payment. |
| Unified Payment Aggregators (Chapa) | Single API integration supporting Telebirr, CBE Birr, Awash Birr, and international cards simultaneously. | Businesses wanting multiple payment options through one administrative dashboard and contract. | Checkout modal presenting Telebirr alongside bank transfer and card options. |
All integration modes require an approved Telebirr Merchant Account with Ethio Telecom.
Prerequisites: How to Obtain Telebirr Merchant Credentials from Ethio Telecom
Before writing any code, your business must register an official Merchant Account with Ethio Telecom. The following commercial documentation is required:
- Valid Ethiopian Business License (Renewed for the current fiscal year).
- Taxpayer Identification Number (TIN) Certificate from Ministry of Revenues.
- Commercial Registration Certificate and Memorandum of Association (for PLC and Share Companies).
- Official Corporate Bank Account details registered under the business entity name.
- Telebirr Merchant Application Form and Signed Service Level Agreement.
- Once approved, Ethio Telecom provides developer sandbox credentials: App ID, App Key, Public Key, and Short Code.
Step-by-Step Technical Implementation Workflow
Implementing a secure Telebirr integration requires executing a strict cryptographic and transactional workflow:
- Step 1: RSA Key Generation and Security SetupGenerate a 2048-bit RSA key pair. The private key remains securely stored on your backend server environment. The public key is uploaded to the Ethio Telecom developer portal to sign transaction payloads.
- Step 2: Constructing the Payment Request PayloadWhen a customer initiates checkout, your backend compiles the transaction parameters: merchantOrderId, totalAmount, title, notifyUrl, and returnUrl. The JSON payload is encrypted using the Telebirr public key and signed using your private key.
- Step 3: Dispatching to Telebirr API and Handling ResponseYour server sends the signed payload via HTTPS POST to the Telebirr payment initialization endpoint. Telebirr validates the signature and returns a checkout URL or transaction token.
- Step 4: Asynchronous Webhook Notification (notifyUrl)Once the user approves the transaction on their phone, Telebirr sends an asynchronous server-to-server webhook notification to your callback URL. Your server must verify the cryptographic signature on this notification before marking the order as paid.
- Step 5: Idempotency and Order Status ReconciliationDue to network drops, webhooks may be retried. Your backend database must enforce idempotent transaction handling so duplicate webhook calls do not double-credit orders. An automated cron worker queries Telebirr order status for pending orders.
Common Technical Mistakes in Telebirr Integration
Many developers in Ethiopia struggle with Telebirr integration due to common implementation errors:
- Relying Solely on the Return URL: Never update order status based on the front-end redirect URL. A customer closing their browser before redirecting will cause orders to remain unpaid despite funds being deducted. Always rely on the server-side notifyUrl webhook.
- Incorrect RSA Padding Schemes: Telebirr APIs require specific RSA PKCS#1 padding. Mismatched padding configurations will trigger obscure invalid signature error codes.
- Hardcoding API Keys in Client-Side Code: Never expose your Telebirr App Key or private key in frontend JavaScript or mobile app binaries. All cryptographic signing must execute on your secure server backend.
- Neglecting Network Timeouts: Because mobile data connections can drop, build robust retry mechanisms and clear transaction logging so customer support can resolve edge-case transaction disputes instantly.
Turnkey Telebirr and Payment Gateway Integration by Zoha
Zoha Global Solutions provides complete, enterprise-grade payment integration services for Ethiopian companies. Whether you operate a custom Next.js web application, WooCommerce store, mobile app, or ERP platform, our engineers configure bulletproof payment automation.
We handle the entire process: assisting with Ethio Telecom merchant account onboarding, writing secure backend API endpoints, implementing automated transaction reconciliation, and testing edge cases.
Visit our engineering office at Alfoz Plaza in Gerji, Addis Ababa, or contact our team directly on +251 94 832 8000 to automate your digital payment workflows.
Questions people ask
Speak Directly with Our Senior Software Architects
Skip the sales runaround. Get an honest technical evaluation of your website, app, or software system within one business day.
Guaranteed confidential review under strict professional NDA standards.
Or submit our detailed project enquiry formAutomate Telebirr payments for your business today
Stop chasing manual transfer receipts. Consult with our fintech integration engineers in Addis Ababa. Call +251 94 832 8000 to review integration options.