Files
sdk-php/README.md
T
admin f0e5be1419 docs: fix the install command — it did not work
Every SDK shipped an install command that fails. A developer following the
README hits an error on the first step.

- go: `go get github.com/qbirr/sdk-go` pointed at GitHub. The module lives at
  git.qbirr.com/admin/sdk-go (see go.mod), so that command could never work.
- node / python / php: the commands assumed a published package, but nothing is
  on npm, PyPI or Packagist yet (all four return 404).

The commands are now the ones that were actually run and verified:
  go      go get git.qbirr.com/admin/sdk-go
  node    npm install git+https://git.qbirr.com/admin/sdk-node.git
  python  pip install "git+https://git.qbirr.com/admin/sdk-python.git"
  php     composer config repositories.qbirr vcs <repo>
          composer require qbirr/sdk:dev-main

A note under each explains that the package is not on the public registry yet,
so the install comes straight from the repository.

The repositories stay public, so no credentials are needed for any of the above.
If they were made private, the Go install would break first: Go fetches modules
directly from the git host.
2026-10-06 01:17:51 +03:00

3.1 KiB

qbirr/sdk (PHP)

Verify Ethiopian bank transfer receipts in real time.

Install

composer config repositories.qbirr vcs https://git.qbirr.com/admin/sdk-php.git
composer require qbirr/sdk:dev-main

These packages are not on the public registries yet, so the command above installs straight from the repository.

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