- The example account number in the README and in the source docblock was a REAL account number. Replaced with an obviously fake one (1000123456789). The same scrub had already been applied to sdks/ in qbirr-saas; this repo had drifted from it. - Document that CBE accepts the full receipt link, the "v2-" token and the bare token as the SAME payment. qbirr reduces them to one identity, so a receipt cannot be verified twice by presenting it differently. Case is ignored for that check. - Document the webhook contract: `verification.created` fires for BOTH outcomes so always read data.verified; data.client_ref echoes the tag your own upload sent (null if you did not send one); a 4xx response is final and is NOT retried, while 5xx / timeouts are retried with exponential backoff. - Document that only verified lookups count against the monthly quota. - sdk-node: the committed dist/ comment blocks were updated to match src. The change is inside comments only — no executable code differs.
2.9 KiB
qbirr/sdk (PHP)
Verify Ethiopian bank transfer receipts in real time.
Install
composer require qbirr/sdk
Requires PHP 7.4+ and the curl + json extensions (standard on almost every host).
Quick start
use Qbirr\Qbirr;
$qb = new Qbirr($_ENV['QBIRR_API_KEY']);
$r = $qb->verify([
'provider' => 'cbe',
'ref' => 'FT23001234ABC',
'amount' => 500,
'receiver_name' => 'YOUR FULL NAME',
'receiver_account' => '1000123456789',
]);
if ($r['verified']) {
echo "Paid by " . $r['payer'] . ", amount: " . $r['amount'];
} else {
echo "Failed: " . $r['error'];
}
Drop-in for WordPress / Laravel / vanilla PHP
Works the same in every framework — it's just curl under the hood.
// WordPress / WooCommerce — inside a payment gateway
$r = (new Qbirr\Qbirr(get_option('qbirr_api_key')))->verify([...]);
// Laravel
$r = (new \Qbirr\Qbirr(config('services.qbirr.key')))->verify([...]);
// Vanilla
require 'vendor/autoload.php';
$r = (new Qbirr\Qbirr(getenv('QBIRR_API_KEY')))->verify([...]);
Reference formats
ref accepts whatever the customer pasted. For CBE, all of these are the
same payment, and qbirr reduces them to a single identity so one receipt
cannot be verified twice:
| What the customer pasted | Example |
|---|---|
| The full receipt link | https://mbreciept.cbe.com.et/v2-hfHCxHoqlCB1LfGG6kJY |
The token with its v2- prefix |
v2-hfHCxHoqlCB1LfGG6kJY |
| Just the token | hfHCxHoqlCB1LfGG6kJY |
The legacy FT… reference |
FT262693ZS18 |
Case is ignored when deciding whether a receipt has already been used. Awash
takes the SMS URL or its token; eBirr takes the URL or "tenant/token".
Webhooks
Subscribe from the dashboard. qbirr POSTs verification.created for both
outcomes, so always read data.verified — never treat delivery alone as payment.
X-Qbirr-Signature: sha256=<hex> # HMAC-SHA256(secret, "<timestamp>.<raw body>")
X-Qbirr-Timestamp: <unix seconds>
X-Qbirr-Event: verification.created
X-Qbirr-Delivery: <delivery id>
data.client_ref echoes the tag your own upload sent, so an order can be found
without inferring it from the provider and amount. It is null if you did not
send one.
Answer 2xx once you have processed the event. A 4xx is final — qbirr will
not retry a request your endpoint refused. Return 5xx (or time out) to have
it retried with exponential backoff.
Quota
Only verified lookups count against your monthly quota. A failed, retryable or duplicate lookup does not consume quota.
Errors
use Qbirr\Qbirr;
use Qbirr\QbirrException;
try {
$r = $qb->verify([ ... ]);
} catch (QbirrException $e) {
error_log("qbirr error " . $e->status . ": " . $e->getMessage());
}
Verification failures (wrong amount, wrong receiver) are not exceptions — they're returned as ['verified' => false, 'error' => '...'].
License
MIT