sdk-node/README.md

@qbirr/sdk

Verify Ethiopian bank transfer receipts in real time — CBE, Telebirr, Awash, Dashen, M-Pesa, Bank of Abyssinia, and eBirr.

Install

npm install @qbirr/sdk

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: '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: '...' }.

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