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.
This commit is contained in:
Vendored
+22
-11
@@ -1,4 +1,3 @@
|
|||||||
"use strict";
|
|
||||||
/**
|
/**
|
||||||
* @qbirr/sdk — Node.js client for the qbirr payment verification API.
|
* @qbirr/sdk — Node.js client for the qbirr payment verification API.
|
||||||
*
|
*
|
||||||
@@ -15,10 +14,25 @@
|
|||||||
*
|
*
|
||||||
* Works on Node 18+ (uses the built-in fetch). No dependencies.
|
* Works on Node 18+ (uses the built-in fetch). No dependencies.
|
||||||
*/
|
*/
|
||||||
Object.defineProperty(exports, "__esModule", { value: true });
|
/**
|
||||||
exports.Qbirr = exports.QbirrError = void 0;
|
* Fill in the additive fields so a consumer never sees `undefined` — including
|
||||||
|
* against an older API that predates them.
|
||||||
|
*/
|
||||||
|
function normalise(r) {
|
||||||
|
return {
|
||||||
|
verified: Boolean(r.verified),
|
||||||
|
payer: String(r.payer ?? ''),
|
||||||
|
error: String(r.error ?? ''),
|
||||||
|
amount: Number(r.amount ?? 0),
|
||||||
|
paid_amount: Number(r.paid_amount ?? 0),
|
||||||
|
retryable: Boolean(r.retryable),
|
||||||
|
code: r.code ?? null,
|
||||||
|
receiver_source: r.receiver_source ?? null,
|
||||||
|
...(r.sandbox ? { sandbox: true } : {}),
|
||||||
|
};
|
||||||
|
}
|
||||||
/** Thrown for network failures, HTTP errors, or non-JSON responses. */
|
/** Thrown for network failures, HTTP errors, or non-JSON responses. */
|
||||||
class QbirrError extends Error {
|
export class QbirrError extends Error {
|
||||||
status;
|
status;
|
||||||
body;
|
body;
|
||||||
constructor(message, status, body) {
|
constructor(message, status, body) {
|
||||||
@@ -28,9 +42,8 @@ class QbirrError extends Error {
|
|||||||
this.name = 'QbirrError';
|
this.name = 'QbirrError';
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
exports.QbirrError = QbirrError;
|
|
||||||
const DEFAULT_BASE_URL = 'https://verify.qbirr.com';
|
const DEFAULT_BASE_URL = 'https://verify.qbirr.com';
|
||||||
class Qbirr {
|
export class Qbirr {
|
||||||
apiKey;
|
apiKey;
|
||||||
baseUrl;
|
baseUrl;
|
||||||
timeoutMs;
|
timeoutMs;
|
||||||
@@ -59,8 +72,7 @@ class Qbirr {
|
|||||||
};
|
};
|
||||||
if (req.receiverAccount)
|
if (req.receiverAccount)
|
||||||
body.receiver_account = req.receiverAccount;
|
body.receiver_account = req.receiverAccount;
|
||||||
const data = await this.request('POST', '/api/v1/verify', body);
|
return normalise(await this.request('POST', '/api/v1/verify', body));
|
||||||
return data;
|
|
||||||
}
|
}
|
||||||
/**
|
/**
|
||||||
* Verify by uploading the receipt itself — PDF or an image (PNG/JPEG).
|
* Verify by uploading the receipt itself — PDF or an image (PNG/JPEG).
|
||||||
@@ -89,7 +101,7 @@ class Qbirr {
|
|||||||
? opts.file
|
? opts.file
|
||||||
: new Blob([opts.file], { type: opts.contentType || 'application/octet-stream' });
|
: new Blob([opts.file], { type: opts.contentType || 'application/octet-stream' });
|
||||||
form.append('file', blob, opts.filename || 'upload.pdf');
|
form.append('file', blob, opts.filename || 'upload.pdf');
|
||||||
return this.requestForm('POST', '/api/v1/verify/upload', form);
|
return normalise(await this.requestForm('POST', '/api/v1/verify/upload', form));
|
||||||
}
|
}
|
||||||
/** Returns the current month's quota usage for this API key. */
|
/** Returns the current month's quota usage for this API key. */
|
||||||
async usage() {
|
async usage() {
|
||||||
@@ -171,5 +183,4 @@ class Qbirr {
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
exports.Qbirr = Qbirr;
|
export default Qbirr;
|
||||||
exports.default = Qbirr;
|
|
||||||
|
|||||||
Vendored
+38
-2
@@ -31,10 +31,46 @@ export interface VerifyResult {
|
|||||||
verified: boolean;
|
verified: boolean;
|
||||||
/** Payer name as extracted from the receipt. */
|
/** Payer name as extracted from the receipt. */
|
||||||
payer: string;
|
payer: string;
|
||||||
/** Amount that was actually paid (per the receipt). */
|
|
||||||
amount: number;
|
|
||||||
/** Human-readable failure reason, empty on success. */
|
/** Human-readable failure reason, empty on success. */
|
||||||
error: string;
|
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 {
|
export interface UsageStatus {
|
||||||
used: number;
|
used: number;
|
||||||
|
|||||||
Vendored
+19
-3
@@ -14,6 +14,23 @@
|
|||||||
*
|
*
|
||||||
* Works on Node 18+ (uses the built-in fetch). No dependencies.
|
* Works on Node 18+ (uses the built-in fetch). No dependencies.
|
||||||
*/
|
*/
|
||||||
|
/**
|
||||||
|
* Fill in the additive fields so a consumer never sees `undefined` — including
|
||||||
|
* against an older API that predates them.
|
||||||
|
*/
|
||||||
|
function normalise(r) {
|
||||||
|
return {
|
||||||
|
verified: Boolean(r.verified),
|
||||||
|
payer: String(r.payer ?? ''),
|
||||||
|
error: String(r.error ?? ''),
|
||||||
|
amount: Number(r.amount ?? 0),
|
||||||
|
paid_amount: Number(r.paid_amount ?? 0),
|
||||||
|
retryable: Boolean(r.retryable),
|
||||||
|
code: r.code ?? null,
|
||||||
|
receiver_source: r.receiver_source ?? null,
|
||||||
|
...(r.sandbox ? { sandbox: true } : {}),
|
||||||
|
};
|
||||||
|
}
|
||||||
/** Thrown for network failures, HTTP errors, or non-JSON responses. */
|
/** Thrown for network failures, HTTP errors, or non-JSON responses. */
|
||||||
export class QbirrError extends Error {
|
export class QbirrError extends Error {
|
||||||
status;
|
status;
|
||||||
@@ -55,8 +72,7 @@ export class Qbirr {
|
|||||||
};
|
};
|
||||||
if (req.receiverAccount)
|
if (req.receiverAccount)
|
||||||
body.receiver_account = req.receiverAccount;
|
body.receiver_account = req.receiverAccount;
|
||||||
const data = await this.request('POST', '/api/v1/verify', body);
|
return normalise(await this.request('POST', '/api/v1/verify', body));
|
||||||
return data;
|
|
||||||
}
|
}
|
||||||
/**
|
/**
|
||||||
* Verify by uploading the receipt itself — PDF or an image (PNG/JPEG).
|
* Verify by uploading the receipt itself — PDF or an image (PNG/JPEG).
|
||||||
@@ -85,7 +101,7 @@ export class Qbirr {
|
|||||||
? opts.file
|
? opts.file
|
||||||
: new Blob([opts.file], { type: opts.contentType || 'application/octet-stream' });
|
: new Blob([opts.file], { type: opts.contentType || 'application/octet-stream' });
|
||||||
form.append('file', blob, opts.filename || 'upload.pdf');
|
form.append('file', blob, opts.filename || 'upload.pdf');
|
||||||
return this.requestForm('POST', '/api/v1/verify/upload', form);
|
return normalise(await this.requestForm('POST', '/api/v1/verify/upload', form));
|
||||||
}
|
}
|
||||||
/** Returns the current month's quota usage for this API key. */
|
/** Returns the current month's quota usage for this API key. */
|
||||||
async usage() {
|
async usage() {
|
||||||
|
|||||||
+64
-5
@@ -42,10 +42,70 @@ export interface VerifyResult {
|
|||||||
verified: boolean;
|
verified: boolean;
|
||||||
/** Payer name as extracted from the receipt. */
|
/** Payer name as extracted from the receipt. */
|
||||||
payer: string;
|
payer: string;
|
||||||
/** Amount that was actually paid (per the receipt). */
|
|
||||||
amount: number;
|
|
||||||
/** Human-readable failure reason, empty on success. */
|
/** Human-readable failure reason, empty on success. */
|
||||||
error: string;
|
error: string;
|
||||||
|
/** The amount you said should have been paid, echoed back. */
|
||||||
|
amount: number;
|
||||||
|
|
||||||
|
/*
|
||||||
|
* The fields below are named exactly as the API sends them (snake_case),
|
||||||
|
* because the SDK returns the response payload as-is.
|
||||||
|
*/
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 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;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Fill in the additive fields so a consumer never sees `undefined` — including
|
||||||
|
* against an older API that predates them.
|
||||||
|
*/
|
||||||
|
function normalise(r: Partial<VerifyResult> & { verified?: boolean }): VerifyResult {
|
||||||
|
return {
|
||||||
|
verified: Boolean(r.verified),
|
||||||
|
payer: String(r.payer ?? ''),
|
||||||
|
error: String(r.error ?? ''),
|
||||||
|
amount: Number(r.amount ?? 0),
|
||||||
|
paid_amount: Number(r.paid_amount ?? 0),
|
||||||
|
retryable: Boolean(r.retryable),
|
||||||
|
code: r.code ?? null,
|
||||||
|
receiver_source: r.receiver_source ?? null,
|
||||||
|
...(r.sandbox ? { sandbox: true } : {}),
|
||||||
|
};
|
||||||
}
|
}
|
||||||
|
|
||||||
export interface UsageStatus {
|
export interface UsageStatus {
|
||||||
@@ -113,8 +173,7 @@ export class Qbirr {
|
|||||||
};
|
};
|
||||||
if (req.receiverAccount) body.receiver_account = req.receiverAccount;
|
if (req.receiverAccount) body.receiver_account = req.receiverAccount;
|
||||||
|
|
||||||
const data = await this.request<VerifyResult>('POST', '/api/v1/verify', body);
|
return normalise(await this.request<VerifyResult>('POST', '/api/v1/verify', body));
|
||||||
return data;
|
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
@@ -152,7 +211,7 @@ export class Qbirr {
|
|||||||
: new Blob([opts.file as unknown as BlobPart], { type: opts.contentType || 'application/octet-stream' });
|
: new Blob([opts.file as unknown as BlobPart], { type: opts.contentType || 'application/octet-stream' });
|
||||||
form.append('file', blob, opts.filename || 'upload.pdf');
|
form.append('file', blob, opts.filename || 'upload.pdf');
|
||||||
|
|
||||||
return this.requestForm<VerifyResult>('POST', '/api/v1/verify/upload', form);
|
return normalise(await this.requestForm<VerifyResult>('POST', '/api/v1/verify/upload', form));
|
||||||
}
|
}
|
||||||
|
|
||||||
/** Returns the current month's quota usage for this API key. */
|
/** Returns the current month's quota usage for this API key. */
|
||||||
|
|||||||
Reference in New Issue
Block a user