Download the PHP package bekambeyene/telebirr without Composer

# Telebirr PHP & Laravel SDK *A Laravel and PHP SDK for Telebirr H5/SuperApp integration with webhook verification, RSA signing, and production-ready interoperability support.* [](https://packagist.org/packages/bekambeyene/telebirr) [](https://packagist.org/packages/bekambeyene/telebirr) [](https://packagist.org/packages/bekambeyene/telebirr) [](https://packagist.org/packages/bekambeyene/telebirr)

This package solves the complex implementation details of Ethiopia's payment gateway. It prioritizes exact interoperability, determinism, and maintainability to guarantee seamless operation in both Telebirr sandbox and production environments. It supports Laravel 12 and 13, alongside Vanilla PHP environments.

🎨 Features

✨ Production-Grade Webhook Handling

• Unified Webhook Verification: Parse and verify incoming webhook requests automatically via Telebirr::handleWebhook(Request $request).
• Clock Drift & Replay Protection: Enforces strict validation of request age and tracks nonces via Laravel's cache.

🚀 Configurable Cryptography & Padding

• RSA-PSS Default Padding: Preorder requests, H5 URLs, and webhook signatures default to modern RSA-PSS.
• Legacy PKCS#1 v1.5 Support: Optionally switch padding modes.

🛠 Robust Canonicalization & Smart Keys

• Stable Sorting: Recursively and deterministically sorts parameter structures, preventing PHP hash-order discrepancies.
• Smart Key Storage Flexibility: Automatically processes raw strings, base64-encoded, or file path PEM keys (file:///path/to/key.pem) without crashing.

📦 Installation

Install the package into your project using Composer:

Publish the configuration file (Laravel):

⚡ Quick Start

Add your credentials to your .env file:

[!TIP] 💡 Smart Key Storage Flexibility To avoid multiline .env string issues, the SDK supports three ways to load keys:

• Raw Base64: Paste just the raw string! The SDK automatically calculates chunking and injects -----BEGIN PRIVATE KEY----- boundaries for you.
• File Path: TELEBIRR_PRIVATE_KEY="file:///var/www/keys/private_key.pem"
• Base64 Strict: TELEBIRR_PRIVATE_KEY="base64:LS0tLS1CRUdJ..."

[!TIP] 💡 Sandbox SSL Issue Adding TELEBIRR_SSL_VERIFY=false to your .env file resolves the "unable to get local issuer certificate" error when connecting to the Telebirr sandbox API.

📱 H5 Payment Controller Example

Below is the recommended controller code you should use when integrating our package.

🛡️ Webhook Verification

[!CAUTION] 🚨 CSRF Middleware Exception Required! Telebirr sends webhooks directly from its servers via a POST request. It does not carry a Laravel CSRF token. If you place your webhook route in routes/web.php without an exception, Laravel will instantly block it with a 419 Page Expired error.

For Laravel 12+: In bootstrap/app.php: $middleware->validateCsrfTokens(except: ['payment/notification']);

For older projects (Laravel 11 and lower): In app/Http/Middleware/VerifyCsrfToken.php: protected $except = ['payment/notification'];

🔍 Signature Troubleshooting

Different Telebirr endpoints use different signature generation rules:

1. Preorder Request Signing

Preorder requests (payment.preorder) compile top-level properties and recursively sort all parameters. Signatures use the configured padding (pss by default).

2. H5 Web Checkout Checkout URL Signing

When launching H5 web checkout redirects, Telebirr expects the URL signature to be calculated on EXACTLY 5 fields:

• appid, merch_code, nonce_str, prepay_id, timestamp.

[!WARNING] ⚠️ Do NOT sign version, trade_type, sign_type, or redirect_url. These optional query parameters must be appended to the redirect URL after generating the signature. Adding them to the signed payload will cause intermittent signature failures (error 60200099).

❌ Common Errors

60200099 Verify the sign field failed

This error means the public key on Telebirr's server cannot verify the signature generated by your private key.

• Signed Field List: Check that H5 signatures only include the 5 required fields.
• Padding Mode mismatch: Telebirr production requires pss (RSA-PSS) padding. Ensure TELEBIRR_SIGNATURE_PADDING matches your gateway settings.
• Accidental double encoding: Ensure you do not URL-encode the parameters twice.

60200087 Organization does not exist

This status indicates the Telebirr gateway/merchant sync services are busy, down, or undergoing synchronization. Always catch TelebirrServerException and prompt users to retry.

✅ Production Best Practices

• Clock Synchronization (NTP): Ensure clock synchronization is enabled on your production servers.
• Idempotency & Database Locks: Acquire database locks on transactions during callback handling.
• Sandbox vs Production Differences: Sandboxes are often more permissive than production systems.

🧪 Testing

Run the tests with:

❓ FAQ

Does Telebirr use RSA-PSS or PKCS1?

By default, recent Telebirr implementations use RSA-PSS. You can switch to PKCS1 by setting TELEBIRR_SIGNATURE_PADDING=pkcs1.

Why am I getting 60200099?

This signature verification failure is commonly caused by including wrong fields in the signed payload, padding mode mismatch, or wrong keys. See # Common Errors.

How do I verify webhooks?

Use the Telebirr::handleWebhook($request) method. It automatically performs deterministic canonicalization, RSA signature verification, nonce replay checking, and timestamp validation.

How do I use Telebirr H5 in Laravel?

Generate the checkout URL using Telebirr::createOrder('Title', $amount) and simply redirect the user using return redirect()->away($url).

Can I use this package without Laravel?

Yes, the core SDK services (SignatureService, TelebirrHttpClient) are framework-agnostic and can be instantiated directly.

📄 License

This SDK is open-sourced software licensed under the MIT License.