Files
sdk-node/README.md
T
admin 322a1154b9 Docs + scrub: neutral example account number, CBE reference formats, webhooks, quota
- The example account number in the README and in the source docblock was a
  REAL account number. Replaced with an obviously fake one (1000123456789).
  The same scrub had already been applied to sdks/ in qbirr-saas; this repo
  had drifted from it.
- Document that CBE accepts the full receipt link, the "v2-" token and the bare
  token as the SAME payment. qbirr reduces them to one identity, so a receipt
  cannot be verified twice by presenting it differently. Case is ignored for
  that check.
- Document the webhook contract: `verification.created` fires for BOTH outcomes
  so always read data.verified; data.client_ref echoes the tag your own upload
  sent (null if you did not send one); a 4xx response is final and is NOT
  retried, while 5xx / timeouts are retried with exponential backoff.
- Document that only verified lookups count against the monthly quota.
- sdk-node: the committed dist/ comment blocks were updated to match src. The
  change is inside comments only — no executable code differs.
2026-10-06 01:05:06 +03:00

120 lines
3.6 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 @qbirr/sdk
```
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