1. Go to this page and download the library: Download melaku/telebirr library. Choose the download type require.
2. Extract the ZIP file and open the index.php.
3. Add this code to the index.php.
<?php
require_once('vendor/autoload.php');
/* Start to develop here. Best regards https://php-download.com/ */
melaku / telebirr example snippets
use Melaku\Telebirr\Config;
use Melaku\Telebirr\Telebirr;
// Configure (test environment)
$config = Config::forTest([
'fabricAppId' => 'YOUR_FABRIC_APP_ID',
'appSecret' => 'YOUR_APP_SECRET',
'merchantAppId' => 'YOUR_MERCHANT_APP_ID',
'merchantCode' => 'YOUR_MERCHANT_CODE',
'privateKey' => 'YOUR_PRIVATE_KEY_PEM',
'notifyUrl' => 'https://your-domain.com/telebirr/notify',
'redirectUrl' => 'https://your-domain.com/telebirr/return',
]);
$client = new Telebirr($config);
// Create checkout URL (one line!). Returns a CheckoutResult.
$result = $client->createCheckoutUrl('Order 123', '100.00');
// IMPORTANT: persist the EXACT merch_order_id the library used — Telebirr
// echoes this value back in notifications and on the return URL. Storing a
// different value (e.g. one you thought you passed) can cause lookup misses.
saveOrder($result->getMerchOrderId(), $result->getPrepayId()); // your code
// Redirect customer to Telebirr
header('Location: ' . $result->getCheckoutUrl());
exit;
// POST /api/create-payment
$result = $client->createInAppPayment('Order 123', '100.00');
// Persist this BEFORE answering. It's how you match the notification.
saveOrder($result->getMerchOrderId(), $result->getPrepayId());
// Send the receiveCode to your mobile app for the SDK to complete the payment.
header('Content-Type: application/json');
echo json_encode($result->toArray()); // { receiveCode, merchOrderId, prepayId }
// Test/Development
$config = Config::forTest([...]);
// Production
$config = Config::forProduction([...]);
// Zero-config: read everything from environment variables
$config = Config::fromEnvironment();
$status = $client->getOrderStatus('YOUR_MERCH_ORDER_ID');
$status->paid; // bool — true ONLY on an explicit success status (fails closed)
$status->tradeStatus; // e.g. 'PAY_SUCCESS'
$status->amount; // e.g. '100.00' — VERIFY this against your own order amount
$status->currency; // 'ETB'
$status->paymentOrderId; // Telebirr's transaction reference (or null)
$status->raw; // the full queryOrder response if you need more
use Melaku\Telebirr\ReturnUrlHandler;
try {
// Fails closed: throws if the signature is missing or invalid.
$paymentData = ReturnUrlHandler::handle($_GET, $config);
if ($paymentData['isSuccess']) {
// The return URL comes through the user's browser and is spoofable even
// when signed. For anything that fulfils an order, confirm the real
// status server-to-server before acting on it:
$status = $client->getOrderStatus($paymentData['merchantOrderId']);
if ($status->paid && $status->amount === $expectedAmount) {
// Update your database / fulfill the order — idempotently (see below).
}
}
} catch (\RuntimeException $e) {
// Missing/invalid signature
http_response_code(400);
echo "Invalid payment data";
}
function settle(Telebirr $client, PDO $db, string $merchOrderId): void
{
$status = $client->getOrderStatus($merchOrderId);
if (!$status->paid) {
return;
}
// Atomic claim: only one caller flips pending → success.
$stmt = $db->prepare(
"UPDATE orders SET status = 'success'
WHERE merch_order_id = :id AND status = 'pending' AND amount = :amount"
);
$stmt->execute(['id' => $merchOrderId, 'amount' => $status->amount]);
if ($stmt->rowCount() === 1) {
fulfillOrder($merchOrderId); // runs exactly once
}
}
use Melaku\Telebirr\NotificationHandler;
use Melaku\Telebirr\Exceptions\TelebirrException;
try {
$payment = NotificationHandler::handle(file_get_contents('php://input'), $config);
} catch (TelebirrException $e) {
// respond* RETURN a NotificationResponse (no header()/echo). In a
// framework, convert it to your Response object. In bare PHP, call send().
NotificationHandler::respondError('Invalid signature', 401)->send();
exit;
}
if ($payment['isSuccess']) {
// Confirm server-to-server before fulfilling — see the settlement pattern above.
$status = $client->getOrderStatus($payment['merchantOrderId']);
if ($status->paid && $status->amount === $expectedAmount) {
// Update database, fulfill order, etc. — idempotently.
}
}
NotificationHandler::respondSuccess('Payment processed')->send();
use Monolog\Logger;
$log = new Logger('telebirr');
$client = new Telebirr($config, $log); // request/response logging (secrets & PII redacted)
use Melaku\Telebirr\Http\HttpClientInterface;
use Melaku\Telebirr\Http\HttpResponse;
$fake = new class implements HttpClientInterface {
public function post(string $url, array $headers, string $body): HttpResponse {
return new HttpResponse(200, '{"token":"Bearer TEST"}');
}
};
$client = new Telebirr($config, null, $fake);
use Melaku\Telebirr\Exceptions\ApiException;
try {
$client->createCheckoutUrl('Order 123', '100.00');
} catch (ApiException $e) {
$e->getHttpStatus(); // e.g. 400
$e->getTelebirrCode(); // e.g. '49401024991' — parsed from the body
$e->getTelebirrMessage(); // Telebirr's errorMsg
$e->getTelebirrSolution(); // Telebirr's errorSolution remediation text
$e->isTransient(); // true for retryable gateway-side failures
$e->getResponseBody(); // raw body, if you need it
}
Loading please wait ...
Before you can download the PHP files, the dependencies should be resolved. This can take some minutes. Please be patient.