a0dcd4fd23be54ebb44a00482d9d4d26429e7b32
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.
@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
Description
Languages
TypeScript
100%