Files
sdk-node/README.md
T
admin eb856ee944 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:50 +03:00

123 lines
3.7 KiB
Markdown

# @qbirr/sdk
Verify Ethiopian bank transfer receipts in real time — CBE, Telebirr, Awash, Dashen, M-Pesa, Bank of Abyssinia, and eBirr.
## Install
```bash
npm install git+https://git.qbirr.com/admin/sdk-node.git
```
These packages are not on the public registries yet, so the command above
installs straight from the repository.
Requires Node.js 18+ (uses built-in `fetch`). Zero dependencies.
## Quick start
```js
import { Qbirr } from '@qbirr/sdk';
const qb = new Qbirr({ apiKey: process.env.QBIRR_API_KEY });
const r = await qb.verify({
provider: 'cbe',
ref: 'FT23001234ABC',
amount: 500,
receiverName: 'YOUR FULL NAME',
receiverAccount: '1000123456789',
});
if (r.verified) {
console.log(`✓ Paid by ${r.payer}, amount: ${r.amount}`);
} else {
console.log(`✗ ${r.error}`);
}
```
## API
### `new Qbirr(options)`
| Option | Required | Default | Description |
|---|---|---|---|
| `apiKey` | ✓ | — | Your key from the qbirr dashboard |
| `baseUrl` | | `https://verify.qbirr.com` | Override (e.g. for self-hosted) |
| `timeoutMs` | | `30000` | Per-request timeout |
### `qb.verify(req)`
| Field | Type | Required | Notes |
|---|---|---|---|
| `provider` | string | ✓ | `cbe` · `telebirr` · `abyssinia` · `dashen` · `mpesa` · `awash` · `ebirr` |
| `ref` | string | ✓ | Transaction reference. For **Awash**, paste the SMS URL or its token. For **eBirr**, paste the URL or `"tenant/token"`. |
| `amount` | number | ✓ | Expected payment amount in ETB |
| `receiverName` | string | ✓ | Exact name on your receiving account |
| `receiverAccount` | string | for CBE & Abyssinia | Your account number |
Returns `{ verified, payer, amount, error }`.
### `qb.usage()`
Returns the current month's `{ used, limit, remaining, plan, period_start, period_end }`.
## 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
`QbirrError` is thrown for network failures, HTTP 4xx/5xx, or non-JSON responses. **Verification failures** (wrong amount, wrong receiver, expired receipt) are NOT thrown — they're returned as `{ verified: false, error: '...' }`.
```js
import { Qbirr, QbirrError } from '@qbirr/sdk';
try {
const r = await qb.verify({ ... });
} catch (e) {
if (e instanceof QbirrError) {
console.error(`API error ${e.status}: ${e.message}`);
}
}
```
## License
MIT