# qbirr/sdk (PHP) Verify Ethiopian bank transfer receipts in real time. ## Install ```bash 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 ```php 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. ```php // 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= # HMAC-SHA256(secret, ".") X-Qbirr-Timestamp: X-Qbirr-Event: verification.created X-Qbirr-Delivery: ``` `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 ```php 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