a0dcd4fd23
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.
144 lines
5.4 KiB
TypeScript
144 lines
5.4 KiB
TypeScript
/**
|
|
* @qbirr/sdk — Node.js client for the qbirr payment verification API.
|
|
*
|
|
* 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 NAME',
|
|
* receiverAccount: '1000017692643',
|
|
* });
|
|
* console.log(r.verified, r.payer);
|
|
*
|
|
* Works on Node 18+ (uses the built-in fetch). No dependencies.
|
|
*/
|
|
export type Provider = 'cbe' | 'telebirr' | 'abyssinia' | 'dashen' | 'mpesa' | 'awash' | 'ebirr' | 'zamzam';
|
|
export interface VerifyRequest {
|
|
provider: Provider;
|
|
/** Transaction reference (or, for Awash/eBirr, the SMS URL / URL token). */
|
|
ref: string;
|
|
/** Expected payment amount in ETB. */
|
|
amount: number;
|
|
/** Exact receiver name (case-insensitive, whitespace-normalised match). */
|
|
receiverName: string;
|
|
/** Required for CBE and Bank of Abyssinia. Ignored for other providers. */
|
|
receiverAccount?: string;
|
|
}
|
|
export interface VerifyResult {
|
|
/** True if the receipt is real, the amount matches, and the receiver matches. */
|
|
verified: boolean;
|
|
/** Payer name as extracted from the receipt. */
|
|
payer: string;
|
|
/** Human-readable failure reason, empty on success. */
|
|
error: string;
|
|
/** The amount you said should have been paid, echoed back. */
|
|
amount: number;
|
|
/**
|
|
* The amount the receipt ACTUALLY shows, in ETB. `0` when unreadable.
|
|
* On a short payment compare it to `amount` to see what arrived — the
|
|
* human-readable `error` tells you the difference but not the figure.
|
|
*/
|
|
paid_amount: number;
|
|
/**
|
|
* TRUE means "we could not reach the bank", so `verified: false` is NOT a
|
|
* verdict on the payment — it is "not checked yet".
|
|
*
|
|
* If this is true, retry or fall back to manual review. Never reject an order
|
|
* on it. Check this BEFORE acting on `verified: false`.
|
|
*/
|
|
retryable: boolean;
|
|
/**
|
|
* Stable machine-readable reason. Branch on this instead of parsing `error`.
|
|
*
|
|
* `RECEIPT_NOT_FOUND` · `AMOUNT_MISMATCH` · `RECEIVER_MISMATCH` ·
|
|
* `RECEIPT_EXPIRED` · `RECEIPT_UNREADABLE` · `REFERENCE_INVALID` ·
|
|
* `RECEIVER_ACCOUNT_REQUIRED` · `UNSUPPORTED_INPUT` · `VERIFICATION_FAILED` ·
|
|
* `DUPLICATE_REFERENCE` · `UPSTREAM_UNAVAILABLE` (the only retryable one).
|
|
* `null` on success.
|
|
*/
|
|
code: string | null;
|
|
/**
|
|
* Which receiver identity was actually checked.
|
|
*
|
|
* `'settings'` — your saved account in the dashboard (strongest).
|
|
* `'request'` — the receiver_name/receiver_account you sent.
|
|
* `'none'` — NOTHING was checked. `verified: true` with `'none'` means the
|
|
* reference exists and the amount matches, but says nothing
|
|
* about who received the money.
|
|
*/
|
|
receiver_source: 'settings' | 'request' | 'none' | null;
|
|
/** Only present on sandbox (`TEST-…`) responses. */
|
|
sandbox?: boolean;
|
|
}
|
|
export interface UsageStatus {
|
|
used: number;
|
|
limit: number;
|
|
remaining: number;
|
|
plan: string;
|
|
/** ISO date — first instant of the current monthly window. */
|
|
period_start: string;
|
|
/** ISO date — first instant of the next monthly window. */
|
|
period_end: string;
|
|
}
|
|
export interface QbirrOptions {
|
|
/** Your API key from the qbirr dashboard. */
|
|
apiKey: string;
|
|
/** Override base URL. Defaults to https://verify.qbirr.com */
|
|
baseUrl?: string;
|
|
/** Per-request timeout (ms). Defaults to 30 000. */
|
|
timeoutMs?: number;
|
|
/** Optional fetch override (for tests). */
|
|
fetch?: typeof fetch;
|
|
}
|
|
/** Thrown for network failures, HTTP errors, or non-JSON responses. */
|
|
export declare class QbirrError extends Error {
|
|
readonly status?: number | undefined;
|
|
readonly body?: unknown | undefined;
|
|
constructor(message: string, status?: number | undefined, body?: unknown | undefined);
|
|
}
|
|
export declare class Qbirr {
|
|
private readonly apiKey;
|
|
private readonly baseUrl;
|
|
private readonly timeoutMs;
|
|
private readonly fetchFn;
|
|
constructor(opts: QbirrOptions);
|
|
/**
|
|
* Verify a single transaction. Returns `{ verified: false, error: '...' }`
|
|
* on a real verification failure (wrong amount, wrong receiver, expired
|
|
* receipt). Throws QbirrError for network/auth problems.
|
|
*/
|
|
verify(req: VerifyRequest): Promise<VerifyResult>;
|
|
/**
|
|
* Verify by uploading the receipt itself — PDF or an image (PNG/JPEG).
|
|
* Images with a QR code (most bank receipts have one) are decoded and
|
|
* routed through the URL-based flow automatically.
|
|
*
|
|
* const buf = await fs.readFile('receipt.pdf');
|
|
* await qb.verifyUpload({
|
|
* provider: 'cbe',
|
|
* amount: 999,
|
|
* receiverName: 'YOUR NAME',
|
|
* receiverAccount: '1000017692643',
|
|
* file: buf,
|
|
* filename: 'receipt.pdf',
|
|
* contentType: 'application/pdf',
|
|
* });
|
|
*/
|
|
verifyUpload(opts: {
|
|
provider: Provider;
|
|
amount: number;
|
|
receiverName: string;
|
|
receiverAccount?: string;
|
|
file: Buffer | Uint8Array | Blob;
|
|
filename?: string;
|
|
contentType?: string;
|
|
}): Promise<VerifyResult>;
|
|
/** Returns the current month's quota usage for this API key. */
|
|
usage(): Promise<UsageStatus>;
|
|
private requestForm;
|
|
private request;
|
|
}
|
|
export default Qbirr;
|