f0e5be1419
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.
114 lines
3.1 KiB
Markdown
114 lines
3.1 KiB
Markdown
# 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=<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
|
|
|
|
```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
|