79 lines
2.1 KiB
Markdown
79 lines
2.1 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: '1000017692643',
|
|
});
|
|
|
|
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 }`.
|
|
|
|
## 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
|