# @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= # HMAC-SHA256(secret, ".") X-Qbirr-Timestamp: X-Qbirr-Event: verification.created X-Qbirr-Delivery: ``` `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