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

ActiveLibrary

telebirr/laravel-bridge
=======================

Laravel integration for the Telebirr payment SDK

00PHP

Since Jul 14Pushed 1mo agoCompare

[ Source](https://github.com/7Doyo/laravel-bridge)[ Packagist](https://packagist.org/packages/telebirr/laravel-bridge)[ RSS](/packages/telebirr-laravel-bridge/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependenciesVersions (1)Used By (0)

Telebirr Laravel Bridge
=======================

[](#telebirr-laravel-bridge)

🚧 **Project Status: In Development**
This project is currently active and under heavy development. Things are changing rapidly, and not all features are fully functional yet. Check back often for updates! Laravel integration for the [Telebirr Payment Gateway](https://developerportal.ethiotelebirr.et/). Wraps the headless [`telebirr/sdk-core`](../php-core/README.md) package with Laravel-native service providers, facades, helper functions, route registration, event dispatching, and localization.

Requirements
------------

[](#requirements)

DependencyVersionPHP>= 8.1Laravel10.x, 11.x, or 12.x`telebirr/sdk-core`^0.1.0 (installed automatically)Installation
------------

[](#installation)

```
composer require telebirr/laravel-bridge
```

The service provider and facade are auto-discovered by Laravel. No manual registration is required.

### Publish Assets

[](#publish-assets)

```
# Publish configuration file to config/telebirr.php
php artisan vendor:publish --tag=telebirr-config

# Publish translation files to lang/vendor/telebirr/
php artisan vendor:publish --tag=telebirr-lang
```

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

[](#configuration)

Add the following variables to your `.env` file:

```
TELEBIRR_ENVIRONMENT=SANDBOX
TELEBIRR_FABRIC_APP_ID=5f0b1a2c-3d4e-5f6a-7b8c-9d0e1f2a3b4c
TELEBIRR_MERCHANT_APP_ID=12345
TELEBIRR_MERCHANT_CODE=TEST_MERCHANT
TELEBIRR_API_KEY=sk_test_xxxxxxxxxxxxxxxx
TELEBIRR_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nMIIEv..."
TELEBIRR_SHORT_CODE=220311
TELEBIRR_TIMEOUT=120m
TELEBIRR_NOTIFY_URL=https://your-app.com/telebirr/webhook
```

### Configuration Reference

[](#configuration-reference)

KeyEnv VariableDefaultDescription`environment``TELEBIRR_ENVIRONMENT``SANDBOX``SANDBOX` or `PRODUCTION``fabric_app_id``TELEBIRR_FABRIC_APP_ID``''`UUID from the Telebirr developer portal`merchant_app_id``TELEBIRR_MERCHANT_APP_ID``''`Numeric merchant application ID`merchant_code``TELEBIRR_MERCHANT_CODE``''`Merchant code`api_key``TELEBIRR_API_KEY``''`Application secret (appSecret)`private_key``TELEBIRR_PRIVATE_KEY``''`PKCS#8 PEM-formatted private key for signing`short_code``TELEBIRR_SHORT_CODE``220311`Payee short code`timeout``TELEBIRR_TIMEOUT``120m`Order timeout expression`notify_url``TELEBIRR_NOTIFY_URL``''`Webhook callback URL`base_url``TELEBIRR_BASE_URL``null`Override API base URL (optional)`locale``TELEBIRR_LOCALE``app.locale`Active locale for trans() strings`fallback_locale``TELEBIRR_FALLBACK_LOCALE``app.fallback_locale`Fallback locale`listeners`--`[]`Event-to-listener mappings (see below)### Environment Guard

[](#environment-guard)

Keys prefixed with `sk_test_` are restricted to the `SANDBOX` environment. Keys prefixed with `sk_live_` are restricted to `PRODUCTION`. Using a key in the wrong environment throws a RuntimeException at boot.

Route Registration
------------------

[](#route-registration)

The service provider registers two routes automatically during `boot()`:

MethodURINameHandler`POST``/telebirr/webhook``telebirr.webhook``WebhookController``POST``/telebirr/refund``telebirr.refund``RefundController::store`To register routes under an `api` prefix instead, call the static helper in your `routes/api.php`:

```
use Telebirr\Laravel\Routes\WebhookRoutes;

WebhookRoutes::registerApi();
```

This produces `/api/telebirr/webhook` and `/api/telebirr/refund`.

Webhook Handling
----------------

[](#webhook-handling)

### How It Works

[](#how-it-works)

1. Telebirr sends a `POST` request to your webhook URL.
2. `WebhookController` verifies the RSA signature against the configured private key.
3. If valid, a `WebhookReceived` event is dispatched with the full payload array.
4. The controller returns `{ "status": "ok" }` with a `200` response.

If signature verification fails, a `401` response is returned and no event is dispatched.

### Events

[](#events)

EventPropertiesDescription`WebhookReceived``payload: array`Fired for every valid webhook. Contains the raw Telebirr payload.`PaymentSucceeded``orderId: string`, `response: array`Fired when `trade_status` indicates a completed payment.`PaymentFailed``orderId: string`, `error: string`Fired when `trade_status` indicates a failed payment.### Registering Listeners

[](#registering-listeners)

#### Via Config

[](#via-config)

Add listeners to the `listeners` array in `config/telebirr.php`:

```
'listeners' => [
    \Telebirr\Laravel\Events\PaymentSucceeded::class => [
        \App\Listeners\HandleSuccessfulPayment::class,
    ],
    \Telebirr\Laravel\Events\PaymentFailed::class => [
        \App\Listeners\HandleFailedPayment::class,
    ],
],
```

#### Via EventServiceProvider

[](#via-eventserviceprovider)

```
protected $listen = [
    \Telebirr\Laravel\Events\PaymentSucceeded::class => [
        \App\Listeners\HandleSuccessfulPayment::class,
    ],
];
```

### Listener Example

[](#listener-example)

```