admin a0dcd4fd23 feat: expose paid_amount, retryable, code, receiver_source, sandbox
The API returns five fields the SDKs were dropping, so a caller could not
act on any of them:

  retryable        TRUE means we could not reach the bank. In that case
                   verified=false is NOT a verdict on the payment -- it is
                   "not checked yet". Retry, or fall back to manual review.
                   Never reject an order on it. Check it BEFORE acting on
                   verified=false.
  code             Stable machine-readable reason; branch on this instead of
                   parsing the human-readable error string. Empty/null on
                   success. RECEIPT_NOT_FOUND, AMOUNT_MISMATCH,
                   RECEIVER_MISMATCH, RECEIPT_EXPIRED, RECEIPT_UNREADABLE,
                   REFERENCE_INVALID, RECEIVER_ACCOUNT_REQUIRED,
                   UNSUPPORTED_INPUT, VERIFICATION_FAILED,
                   DUPLICATE_REFERENCE, UPSTREAM_UNAVAILABLE (retryable).
  paid_amount      What the receipt ACTUALLY shows, so a short payment can be
                   compared to the expected figure rather than only described
                   in prose.
  receiver_source  Which receiver identity was actually checked: 'settings'
                   (your saved dashboard account -- strongest), 'request' (the
                   receiver_name/account you sent), or 'none' (NOTHING was
                   checked: verified=true with 'none' means the reference
                   exists and the amount matches, but says nothing about who
                   received the money).
  sandbox          True only on TEST-... responses.

Additive only. Defaults are filled in on the way out so a caller never sees a
missing value, including against an API build that predates these fields.
2026-10-01 00:44:02 +03:00
2026-07-17 16:52:53 +02:00
2026-07-17 16:52:53 +02:00
2026-07-17 16:42:18 +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: '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

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