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:
2026-10-01 00:44:02 +03:00
parent f7e858ca20
commit a0dcd4fd23
4 changed files with 143 additions and 21 deletions
+22 -11
View File
@@ -1,4 +1,3 @@
"use strict";
/**
* @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.
*/
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. */
class QbirrError extends Error {
export class QbirrError extends Error {
status;
body;
constructor(message, status, body) {
@@ -28,9 +42,8 @@ class QbirrError extends Error {
this.name = 'QbirrError';
}
}
exports.QbirrError = QbirrError;
const DEFAULT_BASE_URL = 'https://verify.qbirr.com';
class Qbirr {
export class Qbirr {
apiKey;
baseUrl;
timeoutMs;
@@ -59,8 +72,7 @@ class Qbirr {
};
if (req.receiverAccount)
body.receiver_account = req.receiverAccount;
const data = await this.request('POST', '/api/v1/verify', body);
return data;
return normalise(await this.request('POST', '/api/v1/verify', body));
}
/**
* Verify by uploading the receipt itself — PDF or an image (PNG/JPEG).
@@ -89,7 +101,7 @@ class Qbirr {
? opts.file
: new Blob([opts.file], { type: opts.contentType || 'application/octet-stream' });
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. */
async usage() {
@@ -171,5 +183,4 @@ class Qbirr {
}
}
}
exports.Qbirr = Qbirr;
exports.default = Qbirr;
export default Qbirr;