The API accepts per-call overrides for the underpayment limit ("25" = 25 ETB,
"1%" = one percent) and the receipt age limit (hours, 0 disables), and returns
payer_error alongside error. None of it was in this SDK.
payer_error is the payer-facing wording: show it to the customer, because error
is written for the merchant and can name their own saved accounts.
@qbirr/sdk
Verify Ethiopian bank transfer receipts in real time — CBE, Telebirr, Awash, Dashen, M-Pesa, Bank of Abyssinia, and eBirr.
Install
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
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: '...' }.
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