PHPackages melaku/telebirr - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Payment Processing](/categories/payments) 4. / 5. melaku/telebirr ActiveLibrary[Payment Processing](/categories/payments) melaku/telebirr =============== Telebirr Web Checkout PHP library (modern API, C2B Web Checkout). v2.0.1(3mo ago)161.8k↓50%3MITPHPPHP >=7.4.0 Since Dec 17Pushed 3mo ago2 watchersCompare [ Source](https://github.com/MelakuDemeke/telebirr-php)[ Packagist](https://packagist.org/packages/melaku/telebirr)[ RSS](/packages/melaku-telebirr/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (5)Dependencies (1)Versions (7)Used By (0) [ ![Telebirr](img/telebirrlogo.png "Aimeos")](https://aimeos.org/)Telebirr PHP Library (Web Checkout) =================================== [](#telebirr-php-library-web-checkout) [![](img/telebanner.png)](img/telebanner.png) [![GitHub branch checks state](https://camo.githubusercontent.com/cc1b138c70ef31a778279e55b37c5e12346efa9cc563220d37969d59b5004a1e/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f636865636b732d7374617475732f4d656c616b7544656d656b652f74656c65626972722d7068702f6d61696e)](https://camo.githubusercontent.com/cc1b138c70ef31a778279e55b37c5e12346efa9cc563220d37969d59b5004a1e/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f636865636b732d7374617475732f4d656c616b7544656d656b652f74656c65626972722d7068702f6d61696e)[![GitHub repo size](https://camo.githubusercontent.com/60c7a3abbfe58511f5b426a6271d4e13d57305f7ba6402ef0a5809df55c784ca/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f7265706f2d73697a652f4d656c616b7544656d656b652f74656c65626972722d706870)](https://camo.githubusercontent.com/60c7a3abbfe58511f5b426a6271d4e13d57305f7ba6402ef0a5809df55c784ca/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f7265706f2d73697a652f4d656c616b7544656d656b652f74656c65626972722d706870)[![GitHub issues](https://camo.githubusercontent.com/4edc6226d5ac0bfa1f432d465a52fbe554707e91eb641f2bf05c0847dc3d43c0/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6973737565732f4d656c616b7544656d656b652f74656c65626972722d706870)](https://camo.githubusercontent.com/4edc6226d5ac0bfa1f432d465a52fbe554707e91eb641f2bf05c0847dc3d43c0/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6973737565732f4d656c616b7544656d656b652f74656c65626972722d706870)[![Packagist Downloads](https://camo.githubusercontent.com/700f3fe969d90417650f4ca9535c4359e94e26a0090ea4d453514e64270b6b6b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6d656c616b752f74656c65626972723f636f6c6f723d677265656e266c6f676f3d7061636b6167697374266c6f676f436f6c6f723d7768697465)](https://camo.githubusercontent.com/700f3fe969d90417650f4ca9535c4359e94e26a0090ea4d453514e64270b6b6b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6d656c616b752f74656c65626972723f636f6c6f723d677265656e266c6f676f3d7061636b6167697374266c6f676f436f6c6f723d7768697465)[![Packagist Stars](https://camo.githubusercontent.com/4fe5520843bc2ad7c241aefbef9e0e24ecb1b6becae4221d6bdde52fdaf6f15f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f73746172732f6d656c616b752f74656c65626972723f6c6f676f3d7061636b6167697374266c6f676f436f6c6f723d7768697465)](https://camo.githubusercontent.com/4fe5520843bc2ad7c241aefbef9e0e24ecb1b6becae4221d6bdde52fdaf6f15f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f73746172732f6d656c616b752f74656c65626972723f6c6f676f3d7061636b6167697374266c6f676f436f6c6f723d7768697465)[![GitHub](https://camo.githubusercontent.com/a5cb11964c173a547821a94ee9fb119ea23efede8fd9319e98d62fef886ced82/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f4d656c616b7544656d656b652f74656c65626972722d7068703f7374796c653d666c6174)](https://camo.githubusercontent.com/a5cb11964c173a547821a94ee9fb119ea23efede8fd9319e98d62fef886ced82/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f4d656c616b7544656d656b652f74656c65626972722d7068703f7374796c653d666c6174)[![GitHub Repo stars](https://camo.githubusercontent.com/b29578e0b854d3b8c402adc497fe04e88deefae6248b8354e21fb27fb6bb8b13/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f73746172732f4d656c616b7544656d656b652f74656c65626972722d7068703f6c6f676f3d676974687562267374796c653d666c6174)](https://camo.githubusercontent.com/b29578e0b854d3b8c402adc497fe04e88deefae6248b8354e21fb27fb6bb8b13/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f73746172732f4d656c616b7544656d656b652f74656c65626972722d7068703f6c6f676f3d676974687562267374796c653d666c6174)[![GitHub forks](https://camo.githubusercontent.com/504a72ea6c72a676c87e2021b430baabd1daa98e83904f6f5349c5e6f373a3ba/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f666f726b732f4d656c616b7544656d656b652f74656c65626972722d7068703f6c6f676f3d676974687562267374796c653d66616c74)](https://camo.githubusercontent.com/504a72ea6c72a676c87e2021b430baabd1daa98e83904f6f5349c5e6f373a3ba/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f666f726b732f4d656c616b7544656d656b652f74656c65626972722d7068703f6c6f676f3d676974687562267374796c653d66616c74)[![GitHub commit activity](https://camo.githubusercontent.com/1332bfcff8398b38e87bfde801014b1ed54f8c50cd280c5278ed18dd2b407e01/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f636f6d6d69742d61637469766974792f6d2f4d656c616b7544656d656b652f74656c65626972722d7068703f6c6f676f3d676974687562)](https://camo.githubusercontent.com/1332bfcff8398b38e87bfde801014b1ed54f8c50cd280c5278ed18dd2b407e01/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f636f6d6d69742d61637469766974792f6d2f4d656c616b7544656d656b652f74656c65626972722d7068703f6c6f676f3d676974687562)[![GitHub last commit](https://camo.githubusercontent.com/e6fb5faf2cb742e20f5018ce6ea7904dff282e0f0febe62586daa14d0ed01961/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6173742d636f6d6d69742f4d656c616b7544656d656b652f74656c65626972722d706870)](https://camo.githubusercontent.com/e6fb5faf2cb742e20f5018ce6ea7904dff282e0f0febe62586daa14d0ed01961/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6173742d636f6d6d69742f4d656c616b7544656d656b652f74656c65626972722d706870) A modern PHP library for integrating **Telebirr Web Checkout (C2B)** payments. Telebirr is a mobile money service developed by Huawei and owned by Ethio telecom. This library provides a simple, easy-to-use API for handling Telebirr payments, fully compliant with the [Telebirr H5 C2B Web Payment Integration Guide](https://developer.ethiotelecom.et/docs/H5%20C2B%20Web%20Payment%20Integration%20Quick%20Guide/requestCreateOrder). 🚀 Quick Start ------------- [](#-quick-start) ### Installation [](#installation) ``` composer require melaku/telebirr ``` ### Basic Usage [](#basic-usage) ``` require 'vendor/autoload.php'; use Melaku\Telebirr\Config; use Melaku\Telebirr\Telebirr; // Configure (test environment) $config = Config::forTest([ 'fabricAppId' => 'YOUR_FABRIC_APP_ID', 'appSecret' => 'YOUR_APP_SECRET', 'merchantAppId' => 'YOUR_MERCHANT_APP_ID', 'merchantCode' => 'YOUR_MERCHANT_CODE', 'privateKey' => 'YOUR_PRIVATE_KEY_PEM', 'notifyUrl' => 'https://your-domain.com/telebirr/notify', 'redirectUrl' => 'https://your-domain.com/telebirr/return', ]); $client = new Telebirr($config); // Create checkout URL (one line!) $checkoutUrl = $client->createCheckoutUrl('Order #123', '100.00'); // Redirect customer to Telebirr header('Location: ' . $checkoutUrl); exit; ``` That's it! The library handles token management, order creation, and checkout URL generation automatically. 📋 Configuration --------------- [](#-configuration) ### Required Credentials [](#required-credentials) You'll receive these from Telebirr: - `fabricAppId` - Your Fabric App ID (UUID) - `appSecret` - Your App Secret - `merchantAppId` - Your Merchant App ID - `merchantCode` - Your Merchant Code (6-digit) - `privateKey` - Your RSA Private Key (PEM format) - `notifyUrl` - Server-to-server notification URL (required) - `redirectUrl` - User return URL after payment (optional) ### Environment Setup [](#environment-setup) The library automatically uses the correct URLs based on environment: ``` // Test/Development $config = Config::forTest([...]); // Production $config = Config::forProduction([...]); // Auto-detect from environment variable $config = Config::fromEnvironment([...]); // Set: export TELEBIRR_ENVIRONMENT=production ``` 💡 Key Features -------------- [](#-key-features) - ✅ **Simple API** - One-line checkout URL generation - ✅ **Automatic Token Management** - No need to handle tokens manually - ✅ **Signature Verification** - Built-in helpers for return URLs and notifications - ✅ **Helper Classes** - `ReturnUrlHandler`, `NotificationHandler`, `PaymentStatus` - ✅ **Environment Support** - Automatic test/production URL handling - ✅ **Full Compliance** - Follows Telebirr H5 C2B Web Payment Integration spec 📖 Common Use Cases ------------------ [](#-common-use-cases) ### Handle Payment Return [](#handle-payment-return) ``` use Melaku\Telebirr\ReturnUrlHandler; try { $paymentData = ReturnUrlHandler::handle($_GET, $config); if ($paymentData['isSuccess']) { // Payment successful $orderId = $paymentData['merchantOrderId']; $amount = $paymentData['amount']; // Update your database, fulfill order, etc. } } catch (\RuntimeException $e) { // Signature verification failed http_response_code(400); echo "Invalid payment data"; } ``` ### Handle Payment Notifications [](#handle-payment-notifications) ``` use Melaku\Telebirr\NotificationHandler; $rawData = file_get_contents('php://input'); $notification = NotificationHandler::parse($rawData); // Verify signature if (!NotificationHandler::verify($notification, $config)) { NotificationHandler::respondError('Invalid signature'); exit; } // Process payment if (NotificationHandler::isPaymentSuccessful($notification)) { $paymentInfo = NotificationHandler::extractPaymentInfo($notification); // Update database, fulfill order, etc. NotificationHandler::respondSuccess('Payment processed'); } ``` ### Query Order Status [](#query-order-status) ``` $tokenInfo = $client->applyFabricToken(); $orderStatus = $client->queryOrder($tokenInfo['token'], null, 'YOUR_ORDER_ID'); $tradeStatus = $orderStatus['biz_content']['trade_status'] ?? ''; if (strtoupper($tradeStatus) === 'PAY_SUCCESS') { // Payment successful } ``` ### Process Refund [](#process-refund) ``` $tokenInfo = $client->applyFabricToken(); $refundResult = $client->refundOrder( $tokenInfo['token'], '50.00', // Refund amount 'PAYMENT_ORDER_ID', // or null 'MERCHANT_ORDER_ID', // or null 'Refund reason' // Optional ); ``` 🔧 Requirements -------------- [](#-requirements) - PHP >= 7.4 - `ext-curl` extension - `ext-openssl` extension (used by `notify.php` for payload decryption only) - **phpseclib/phpseclib** (^3.0) — **Signer** and **SignatureVerifier** use phpseclib only (pure-PHP). No OpenSSL CLI or ext-openssl required for signing/verification. Works on all platforms including Windows. Algorithm: RSA-PSS, SHA256, MGF1-SHA256, salt length 32. 📚 Documentation --------------- [](#-documentation) For detailed documentation, API reference, and advanced usage examples, visit our documentation site: **🔗 [Full Documentation](https://telebirr-php-docs.vercel.app)** *(Coming Soon)* The documentation includes: - Complete API reference - Step-by-step integration guides - Advanced configuration options - Signature verification details - Webhook/notification handling - Error handling and troubleshooting - Security best practices 🛠️ Helper Classes ----------------- [](#️-helper-classes) The library provides several helper classes to simplify common tasks: - **`ReturnUrlHandler`** - Parse and verify return URL parameters - **`NotificationHandler`** - Parse and verify payment notifications - **`PaymentStatus`** - Check payment status values - **`SignatureVerifier`** - Verify signatures from Telebirr 🔒 Security Notes ---------------- [](#-security-notes) - Always verify signatures before processing payments - Use HTTPS for all payment endpoints - Store credentials in environment variables, not in code - Implement idempotency checks for notifications - Never trust return URL parameters alone - verify with server-to-server notifications 🤝 Contributing -------------- [](#-contributing) Contributions are welcome! Please feel free to submit a Pull Request. 📄 License --------- [](#-license) This project is licensed under the MIT License. 🔗 Links ------- [](#-links) - [Telebirr Developer Portal](https://developer.ethiotelecom.et/) - [Telebirr H5 C2B Integration Guide](https://developer.ethiotelecom.et/docs/H5%20C2B%20Web%20Payment%20Integration%20Quick%20Guide/requestCreateOrder) - [Packagist](https://packagist.org/packages/melaku/telebirr) - [GitHub Repository](https://github.com/MelakuDemeke/telebirr-php) --- **Need help?** Check out the [full documentation](https://telebirr-php-docs.vercel.app) or open an issue on GitHub. ### Health Score 44 — FairBetter than 92% of packages Maintenance78 Regular maintenance activity Popularity28 Limited adoption so far Community10 Small or concentrated contributor base Maturity50 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~283 days Total 5 Last Release 114d ago Major Versions v0.1.0 → v1.0.0a2022-12-20 v1.0.0a → v2.0.02026-01-23 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/38818398?v=4)[Melaku Demeke](/maintainers/MelakuDemeke)[@MelakuDemeke](https://github.com/MelakuDemeke) --- Top Contributors [![MelakuDemeke](https://avatars.githubusercontent.com/u/38818398?v=4)](https://github.com/MelakuDemeke "MelakuDemeke (41 commits)") --- Tags phptelebirrtelebirr-librarytelebirr-php ### Embed Badge ![Health badge](/badges/melaku-telebirr/health.svg) ``` [![Health](https://phpackages.com/badges/melaku-telebirr/health.svg)](https://phpackages.com/packages/melaku-telebirr) ``` ### Alternatives [amzn/amazon-pay-api-sdk-php Amazon Pay API SDK (PHP) 505.1M9](/packages/amzn-amazon-pay-api-sdk-php)[amzn/amazon-pay-magento-2-module Official Magento2 Plugin to integrate with Amazon Pay 109501.7k1](/packages/amzn-amazon-pay-magento-2-module)[sylius/paypal-plugin PayPal plugin for Sylius. 451.4M4](/packages/sylius-paypal-plugin)[tpay-com/tpay-php Tpay.com library 25260.3k9](/packages/tpay-com-tpay-php)[litle/payments-sdk The Vantiv eCommerce PHP SDK is a PHP implementation of the \[Vantiv eCommerce\](https://developer.vantiv.com/community/ecommerce). XML API. This SDK was created to make it as easy as possible to connect process your payments with Vantiv eCommerce 19139.3k1](/packages/litle-payments-sdk)[saleh7/php-zatca-xml An unofficial PHP library for generating ZATCA Fatoora e-invoices. This library facilitates the creation of compliant e-invoices, QR Codes, and certificates, as well as the submission of e-invoices to ZATCA's servers. It provides developers with an easy-to-use, customizable, and robust toolkit to integrate and automate ZATCA e-invoicing processes in PHP applications. 5112.5k](/packages/saleh7-php-zatca-xml) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)