Download the PHP package dream-technologies/telebirr-laravel-plus without Composer

telebirr-laravel-plus

Flutter integration guide | Telebirr API technical guide

Production-ready Laravel backend package for Telebirr InApp Purchase in Ethiopia.

GitHub: Dream-Technologies-PLC/telebirr-laravel-plus

Using an AI coding assistant to integrate this package into your existing Laravel app? Add or reference skills.md first so the assistant asks for the required Telebirr credentials, private key location, notify URL, existing order model, and checkout controller before changing code.

It is built to pair with the Flutter package:

• telebirr_inapp_purchase_plus on pub.dev
• Flutter GitHub repository

Use this Laravel package on your backend. Use the Flutter package only to open the native Telebirr SDK with the receiveCode returned from Laravel.

What This Package Does

• Applies Fabric Token on the backend.
• Signs Telebirr requests with your private key.
• Creates InApp orders.
• Returns receiveCode for Flutter.
• Provides query-order support.
• Verifies notify callback signatures when Telebirr's callback public key is configured.
• Normalizes callback identifiers, amount, currency, and payment status.
• Supports private keys as protected files, inline PEM, or base64 key bodies.
• Keeps secrets away from Flutter.
• Supports testbed and production environments.

What Flutter Does

Flutter calls your Laravel endpoint:

Laravel returns:

Flutter then starts payment:

Install

This package is published for Laravel through Packagist, the Composer package registry. Packagist is the Laravel/PHP equivalent of pub.dev for Flutter packages.

Publish config:

Add environment variables:

Put your private key in a private backend-only path, for example:

Never place the private key in public/.

For platforms that inject secrets at runtime, TELEBIRR_PRIVATE_KEY also accepts a PEM value, escaped newlines, or the base64 key body. A protected file or secret-manager mount is preferred because it avoids storing a long key in the process environment.

To verify callbacks, configure the callback-verification public key supplied by Telebirr. This is not your merchant private key:

Callback signatures are required by default. Set TELEBIRR_CALLBACK_SIGNATURE_REQUIRED=false only when Telebirr has not provided its callback public key. In that temporary mode, always confirm payment through queryOrder before fulfilling an order or crediting a wallet.

Routes

Routes are registered automatically:

Protect the client routes in production while keeping the Telebirr callback publicly reachable:

Change the route prefix:

Disable built-in routes if you want custom controllers:

Create Order

Request:

Response:

Use In Your Own Controller

Query Order

Use query-order when the Flutter callback is delayed, the user closes the app, or notify_url is delayed.

Handle Notify Callback

The built-in notify route validates and safely logs callback metadata, then dispatches:

Listen to the event in your app to update your own order records:

Never credit a wallet from the Flutter SDK result alone. Use the callback as a signal, verify merchant order ID, amount, and currency against your own record, then confirm final state with backend queryOrder. Make the final update idempotent so duplicate callbacks cannot credit twice.

Security Rules

Keep these on Laravel only:

• App Secret
• Private key
• RSA signing
• Fabric Token
• createOrder
• queryOrder
• notify_url verification

Flutter should receive only receiveCode, merchantOrderId, and safe UI status fields.

The built-in create-order endpoint accepts amount and title for demonstration. For production purchases, use your own authenticated controller, load the price from your database, and pass that server-owned amount to CreateOrderData.

Testbed And Production

Testbed:

Production:

If your organization or contract is not approved, Telebirr may return:

Check your account at developer.ethiotelecom.et and make sure organization members and product contracts are approved.

Local Device Testing

Run Laravel:

Use your computer LAN IP in Flutter, not localhost:

Contact Us

Need support with Telebirr integration, websites, mobile apps, or custom software? Contact Dream Technologies PLC: dreamtech.et/contact