Initial release: qbirr/sdk v1.0.0

2026-07-17 16:42:30 +02:00
commit ce11a3b94d
3 changed files with 270 additions and 0 deletions
@@ -0,0 +1,68 @@
+# qbirr/sdk (PHP)
+
+Verify Ethiopian bank transfer receipts in real time.
+
+## Install
+
+```bash
+composer require qbirr/sdk
+```
+
+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' => '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.
+
+```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([...]);
+```
+
+## 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