admin 10823bcb1b feat: expose paid_amount, retryable, code, receiver_source, sandbox
The API returns five fields the SDKs were dropping, so a caller could not
act on any of them:

  retryable        TRUE means we could not reach the bank. In that case
                   verified=false is NOT a verdict on the payment -- it is
                   "not checked yet". Retry, or fall back to manual review.
                   Never reject an order on it. Check it BEFORE acting on
                   verified=false.
  code             Stable machine-readable reason; branch on this instead of
                   parsing the human-readable error string. Empty/null on
                   success. RECEIPT_NOT_FOUND, AMOUNT_MISMATCH,
                   RECEIVER_MISMATCH, RECEIPT_EXPIRED, RECEIPT_UNREADABLE,
                   REFERENCE_INVALID, RECEIVER_ACCOUNT_REQUIRED,
                   UNSUPPORTED_INPUT, VERIFICATION_FAILED,
                   DUPLICATE_REFERENCE, UPSTREAM_UNAVAILABLE (retryable).
  paid_amount      What the receipt ACTUALLY shows, so a short payment can be
                   compared to the expected figure rather than only described
                   in prose.
  receiver_source  Which receiver identity was actually checked: 'settings'
                   (your saved dashboard account -- strongest), 'request' (the
                   receiver_name/account you sent), or 'none' (NOTHING was
                   checked: verified=true with 'none' means the reference
                   exists and the amount matches, but says nothing about who
                   received the money).
  sandbox          True only on TEST-... responses.

Additive only. Defaults are filled in on the way out so a caller never sees a
missing value, including against an API build that predates these fields.
2026-10-01 00:44:05 +03:00
2026-07-17 16:42:30 +02:00

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' => '1000017692643',
]);

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([...]);

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

S
Description
qbirr SDK - sdk-php
Readme 47 KiB
Languages
PHP 100%