PHP code example of melaku / telebirr

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();

$tokenInfo = $client->applyFabricToken();
$orderStatus = $client->queryOrder($tokenInfo['token'], null, 'YOUR_ORDER_ID');

$tradeStatus = $orderStatus['biz_content']['trade_status'] ?? '';
if (strtoupper($tradeStatus) === 'PAY_SUCCESS') {
    // Payment successful
}

$health = $client->ping(); // never throws
if (!$health['ok']) {
    // show "payment temporarily unavailable" instead of a broken checkout
}

$tokenInfo = $client->applyFabricToken();
$refundResult = $client->refundOrder(
    $tokenInfo['token'],
    '50.00',              // Refund amount
    'PAYMENT_ORDER_ID',   // or null
    'MERCHANT_ORDER_ID',  // or null
    'Refund reason'       // Optional
);

$config = Config::forProduction([
    // ... credentials ...
    'verifySsl'      => true,   // default true — leave on; the library warns (test) or
                                 // logs an error (production) if you turn it off
    'caBundlePath'   => null,   // optional path to a custom CA bundle (PEM);
                                 // supplying one disables the bundled-CA fallback
    'timeout'        => 30,     // total request timeout (seconds)
    'connectTimeout' => 10,     // connection timeout (seconds)
]);

$client = new Telebirr($config, null, null, ['cacheFabricToken' => false]);

$client = new Telebirr($config, $logger, null, [
    'retry' => ['retries' => 2, 'delayMs' => 500, 'maxDelayMs' => 5000],
]);

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
}