PHPackages                             matt-di/laravel-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. matt-di/laravel-telebirr

ActiveLibrary

matt-di/laravel-telebirr
========================

Telebirr payment gateway integration for Laravel applications

v1.0.0(6mo ago)00[1 issues](https://github.com/Matt-di/laravel-telebirr/issues)MITPHPPHP ^8.1CI failing

Since Nov 14Pushed 6mo agoCompare

[ Source](https://github.com/Matt-di/laravel-telebirr)[ Packagist](https://packagist.org/packages/matt-di/laravel-telebirr)[ RSS](/packages/matt-di-laravel-telebirr/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (1)Dependencies (11)Versions (2)Used By (0)

Laravel Telebirr Payment Gateway
================================

[](#laravel-telebirr-payment-gateway)

[![Latest Version on Packagist](https://camo.githubusercontent.com/97fd51ac4a1b69ea3a098bbf81f72d86fbe981a31e1184866819dd1fdb70f42a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f4d6174742d64692f6c61726176656c2d74656c65626972722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/Matt-di/laravel-telebirr)[![Total Downloads](https://camo.githubusercontent.com/f8e2d176a703ed12bbb94e00cca87fc3287c7393b948e07702a354aee986cbd0/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f4d6174742d64692f6c61726176656c2d74656c65626972722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/Matt-di/laravel-telebirr)[![License](https://camo.githubusercontent.com/2a8a1f21d8c16ac843e3bf7e3af65410e826a17d3485e06e00c207ac7a8ddec8/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f4d6174742d64692f6c61726176656c2d74656c65626972722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/Matt-di/laravel-telebirr)

Telebirr payment gateway integration for Laravel applications with support for single and multi-merchant setups.

🎯 Integration Type
------------------

[](#-integration-type)

**This package is designed for Telebirr Super App integration** where the frontend handles payment requests through the Telebirr mobile application.

- **Backend Role:** Generates signed payment requests and handles webhooks
- **Frontend Role:** Uses Telebirr mobile SDK to process payments
- **📖 Frontend Integration:** Refer to [Telebirr Developer Documentation](https://developer.telebirr.et/) for mobile app integration details
- **🔗 Official Resources:** Check Telebirr's official documentation for SDK implementation and best practices

Features
--------

[](#features)

- 🚀 **Simple Setup** - Get started in minutes with zero configuration
- 🏪 **Multi-Merchant Support** - Perfect for multi-branch or multi-store applications
- 🔐 **Enterprise Security** - RSA PSS signatures, webhook verification, SSL controls
- ⚡ **High Performance** - Token caching, queue-based processing, retry logic
- 🛠 **Developer Friendly** - Artisan commands, comprehensive logging, extensive configuration
- 🔧 **Highly Configurable** - Extensive customization options for any use case
- 📱 **Mobile SDK Ready** - Raw request generation for Telebirr mobile applications
- 🎯 **Event Driven** - Laravel events for payment lifecycle hooks

Installation
------------

[](#installation)

### Basic Setup (Single Merchant)

[](#basic-setup-single-merchant)

```
composer require matt-di/laravel-telebirr
php artisan telebirr:install
```

### Multi-Merchant Setup

[](#multi-merchant-setup)

```
composer require Matt-di/laravel-telebirr
php artisan telebirr:install --mode=multi --run-migrations
```

Quick Start
-----------

[](#quick-start)

### 1. Configure Environment

[](#1-configure-environment)

Add your Telebirr credentials to `.env`:

```
# Single merchant mode
TELEBIRR_MODE=single
TELEBIRR_FABRIC_APP_ID=your_fabric_app_id
TELEBIRR_MERCHANT_APP_ID=your_merchant_app_id
TELEBIRR_MERCHANT_CODE=123456
TELEBIRR_APP_SECRET=your_app_secret
TELEBIRR_RSA_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
```

### 2. Create Payment Request

[](#2-create-payment-request)

```
use Telebirr\LaravelTelebirr\Facades\Telebirr;

$rawRequest = Telebirr::initiatePayment([
    'txn_ref' => 'TXN_' . time(),
    'amount' => 150.00,
    'subject' => 'Order Payment'
]);

// Returns: "appid=MERCHANT123&merch_code=MC456&nonce_str=abc...&prepay_id=PRE123...&timestamp=202512021200&sign_type=SHA256WithRSA&sign=signed_data..."
```

### 3. Handle Webhook (Automatically Done)

[](#3-handle-webhook-automatically-done)

The package handles webhook verification, signature checking, and payment verification automatically.

Usage Examples
--------------

[](#usage-examples)

### Single Merchant

[](#single-merchant)

```
// Simple payment initiation
Telebirr::initiatePayment([
    'txn_ref' => 'TXN_123',
    'amount' => 100.00,
    'subject' => 'Product Purchase'
]);
```

### Multi-Merchant (Branch-Based)

[](#multi-merchant-branch-based)

```
// Payment for specific branch
Telebirr::initiatePayment([
    'txn_ref' => 'TXN_123',
    'amount' => 100.00,
    'subject' => 'Branch Order'
], ['branch_id' => 1]);
```

### Custom Context

[](#custom-context)

```
// Organized by stores
Telebirr::initiatePayment($data, ['store_id' => 5]);

// Or even custom types
Telebirr::initiatePayment($data, ['owner_type' => 'restaurant', 'owner_id' => 10]);
```

### Payment Verification

[](#payment-verification)

```
$result = Telebirr::verifyPayment('TXN_123');
if ($result && $result['order_status'] === 'PAY_SUCCESS') {
    // Payment successful
}
```

### Auth Token Retrieval

[](#auth-token-retrieval)

```
$userInfo = Telebirr::getAuthToken($accessToken);
```

### Error Handling

[](#error-handling)

```
try {
    $paymentRequest = Telebirr::initiatePayment([
        'txn_ref' => 'TXN_' . time(),
        'amount' => 150.00,
        'subject' => 'Order Payment',
    ]);

    // Process successful payment initiation

} catch (\Telebirr\LaravelTelebirr\Exceptions\TelebirrException $e) {
    // Handle payment initiation errors
    Log::error('Telebirr payment failed: ' . $e->getMessage());

    // Show user-friendly error message
    return back()->withErrors(['payment' => 'Payment initiation failed. Please try again.']);
}
```

Event Listeners
---------------

[](#event-listeners)

Listen to payment lifecycle events:

```
Event::listen(Telebirr\LaravelTelebirr\Events\PaymentInitiated::class, function ($event) {
    // Payment initiated
});

Event::listen(Telebirr\LaravelTelebirr\Events\PaymentVerified::class, function ($event) {
    // Payment verified and successful
    // Update your order/invoice status here
});

Event::listen(Telebirr\LaravelTelebirr\Events\WebhookReceived::class, function ($event) {
    // Raw webhook received
});
```

Testing
-------

[](#testing)

Test your integration:

```
# Test API connectivity
php artisan telebirr:test-connection

# Setup and test webhooks
php artisan telebirr:setup-webhook --test
```

Configuration
-------------

[](#configuration)

### Single Merchant Mode

[](#single-merchant-mode)

- Uses global ENV configuration
- No database required
- Perfect for simple applications

### Multi-Merchant Mode

[](#multi-merchant-mode)

- Database-driven merchant management
- Configurable relationship mappings
- Enterprise-ready for complex applications

API Reference
-------------

[](#api-reference)

### Facade Methods

[](#facade-methods)

```
Telebirr::initiatePayment(array $data, array $context = [])
Telebirr::verifyPayment(string $transactionId, array $context = [])
Telebirr::queryOrder(string $orderId, array $context = [])
Telebirr::getAuthToken(string $accessToken, array $context = [])
Telebirr::handleWebhook(Request $request)
```

### HTTP Endpoints

[](#http-endpoints)

- `POST /api/telebirr/order` - Create payment order
- `POST /api/telebirr/verify` - Verify payment status
- `POST /api/telebirr/query` - Query order details
- `POST /api/telebirr/auth` - Get auth token
- `POST /api/telebirr/webhook` - Webhook handler

Advanced Configuration
----------------------

[](#advanced-configuration)

Publish config for full customization:

```
php artisan vendor:publish --tag=telebirr-config
```

### Custom Merchant Resolver

[](#custom-merchant-resolver)

```
// config/telebirr.php
'merchant' => [
    'resolver' => App\Services\CustomMerchantResolver::class,
],
```

### Custom Webhook Handler

[](#custom-webhook-handler)

```
'webhook' => [
    'handler' => App\Services\CustomWebhookHandler::class,
],
```

Migration Guide
---------------

[](#migration-guide)

### From Single to Multi-Merchant

[](#from-single-to-multi-merchant)

1. Change mode: `TELEBIRR_MODE=multi`
2. Run: `php artisan telebirr:install --mode=multi --run-migrations`
3. Add merchant records to `telebirr_merchants` table
4. Update code to pass merchant context where needed

Complete Integration Example
----------------------------

[](#complete-integration-example)

Here's a complete real-world integration example:

```