devLap

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

php dev.to

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

60200099 Verify the sign field failed
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Publish the config:

php artisan vendor:publish --tag="telebirr-config"
Enter fullscreen mode Exit fullscreen mode

Example Laravel Usage

Create an H5 payment:

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

return redirect()->away($paymentUrl);
Enter fullscreen mode Exit fullscreen mode

Webhook verification:

$payload = Telebirr::handleWebhook($request);
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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

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

Feedback, issues, and contributions are welcome.

Tags

laravel php opensource payments ethiopia sdk

Source: dev.to

arrow_back Back to Tutorials