I Built an Open Source Telebirr SDK for Laravel After Fighting Signature Failures for Days

Bekam B — Wed, 10 Jun 2026 10:25:51 +0000

If you've integrated Telebirr in Laravel or PHP before, you've probably seen this error:

60200099 Verify the sign field failed

At first it looks simple.

Then you spend hours debugging:

RSA padding
parameter ordering
webhook verification
H5 signing rules
PEM formatting
sandbox vs production differences

…and nothing works consistently.

After dealing with these problems repeatedly, I decided to build a production-focused Telebirr PHP & Laravel SDK that handles the interoperability issues automatically.

GitHub Repository

https://github.com/OgBek/Telebirr-laravel-package-sdk

The Biggest Problem Wasn't the API

The actual API calls are easy.

The hard part was making signatures work reliably across:

sandbox
production
different PHP environments
Laravel request handling
H5 redirect signing

I found that many integration examples online:

signed the wrong fields
used inconsistent sorting
mixed RSA-PSS and PKCS1
ignored replay protection
failed in production even when sandbox worked

One Tiny Mistake Breaks Everything

For example, Telebirr H5 signing only expects these fields:

appid
merch_code
nonce_str
prepay_id
timestamp

If you accidentally include fields like:

version
trade_type
redirect_url

inside the signed payload, you'll randomly get signature failures.

That single issue alone wasted a ridiculous amount of debugging time.

What the SDK Handles

The package now automatically handles:

RSA-PSS signing
Optional PKCS1 support
Deterministic recursive sorting
Webhook verification
Replay attack protection
Timestamp validation
Smart PEM key loading
Laravel integration
Vanilla PHP compatibility

Installation

composer require bekambeyene/telebirr

Publish the config:

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

Example Laravel Usage

Create an H5 payment:

$paymentUrl = Telebirr::createOrder(
    'Premium Subscription',
    250.00,
    'ORDER-' . uniqid()
);

return redirect()->away($paymentUrl);

Webhook verification:

$payload = Telebirr::handleWebhook($request);

The SDK automatically validates:

signatures
timestamps
nonce replay attempts

One Unexpected Issue: PEM Keys

A surprisingly annoying issue was .env key formatting.

Some developers:

store raw keys
use base64
use file paths
accidentally break multiline formatting

The SDK now supports:

TELEBIRR_PRIVATE_KEY="file:///var/www/keys/private_key.pem"

as well as raw/base64 formats automatically.

Production vs Sandbox Is Different

One thing I learned quickly:

Sandbox success does NOT guarantee production success.

Production Telebirr environments tend to be stricter about:

padding modes
timestamps
payload ordering
signature consistency

So the package focuses heavily on deterministic behavior.

Security Features

The SDK includes:

replay attack detection
timestamp expiration validation
strict webhook verification
deterministic canonicalization
configurable RSA padding

Why I Open Sourced It

There aren't many well-maintained open source Telebirr integrations focused on Laravel and production interoperability.

I wanted to build something developers could actually rely on instead of repeatedly debugging cryptographic edge cases.

Repository