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
2026-07-17 16:52:53 +02:00
2026-07-17 16:52:53 +02:00

@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: '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

S
Description
qbirr SDK - sdk-node
Readme 73 KiB
Languages
TypeScript 100%