Document tolerance, max_age_hours and payer_error

The API accepts per-call overrides for the underpayment limit ("25" = 25 ETB,
"1%" = one percent) and the receipt age limit (hours, 0 disables), and returns
payer_error alongside error. None of it was in this SDK.

payer_error is the payer-facing wording: show it to the customer, because error
is written for the merchant and can name their own saved accounts.
This commit is contained in:
qbirr agent
2026-10-06 19:34:08 +03:00
parent eb856ee944
commit 5008b3de5a
+15
View File
@@ -35,6 +35,10 @@ export interface VerifyRequest {
receiverName: string; receiverName: string;
/** Required for CBE and Bank of Abyssinia. Ignored for other providers. */ /** Required for CBE and Bank of Abyssinia. Ignored for other providers. */
receiverAccount?: string; receiverAccount?: string;
/** Overrides the saved underpayment limit for this call: "25" = 25 ETB, "1%" = one percent. */
tolerance?: string;
/** Overrides the saved receipt age limit for this call, in hours. 0 disables it for this call. */
maxAgeHours?: number;
} }
export interface VerifyResult { export interface VerifyResult {
@@ -86,6 +90,8 @@ export interface VerifyResult {
* about who received the money. * about who received the money.
*/ */
receiver_source: 'settings' | 'request' | 'none' | null; receiver_source: 'settings' | 'request' | 'none' | null;
/** Same failure, written for the CUSTOMER. Show this to the payer, not `error`. */
payer_error: string | null;
/** Only present on sandbox (`TEST-…`) responses. */ /** Only present on sandbox (`TEST-…`) responses. */
sandbox?: boolean; sandbox?: boolean;
} }
@@ -104,6 +110,7 @@ function normalise(r: Partial<VerifyResult> & { verified?: boolean }): VerifyRes
retryable: Boolean(r.retryable), retryable: Boolean(r.retryable),
code: r.code ?? null, code: r.code ?? null,
receiver_source: r.receiver_source ?? null, receiver_source: r.receiver_source ?? null,
payer_error: r.payer_error ?? null,
...(r.sandbox ? { sandbox: true } : {}), ...(r.sandbox ? { sandbox: true } : {}),
}; };
} }
@@ -172,6 +179,8 @@ export class Qbirr {
receiver_name: req.receiverName, receiver_name: req.receiverName,
}; };
if (req.receiverAccount) body.receiver_account = req.receiverAccount; if (req.receiverAccount) body.receiver_account = req.receiverAccount;
if (req.tolerance) body.tolerance = req.tolerance;
if (req.maxAgeHours !== undefined) body.max_age_hours = req.maxAgeHours;
return normalise(await this.request<VerifyResult>('POST', '/api/v1/verify', body)); return normalise(await this.request<VerifyResult>('POST', '/api/v1/verify', body));
} }
@@ -197,6 +206,10 @@ export class Qbirr {
amount: number; amount: number;
receiverName: string; receiverName: string;
receiverAccount?: string; receiverAccount?: string;
/** Overrides the saved underpayment limit for this call: "25" = 25 ETB, "1%" = one percent. */
tolerance?: string;
/** Overrides the saved receipt age limit for this call, in hours. 0 disables it for this call. */
maxAgeHours?: number;
file: Buffer | Uint8Array | Blob; file: Buffer | Uint8Array | Blob;
filename?: string; filename?: string;
contentType?: string; contentType?: string;
@@ -206,6 +219,8 @@ export class Qbirr {
form.append('amount', String(opts.amount)); form.append('amount', String(opts.amount));
form.append('receiver_name', opts.receiverName); form.append('receiver_name', opts.receiverName);
if (opts.receiverAccount) form.append('receiver_account', opts.receiverAccount); if (opts.receiverAccount) form.append('receiver_account', opts.receiverAccount);
if (opts.tolerance) form.append('tolerance', opts.tolerance);
if (opts.maxAgeHours !== undefined) form.append('max_age_hours', String(opts.maxAgeHours));
const blob = opts.file instanceof Blob const blob = opts.file instanceof Blob
? opts.file ? opts.file
: 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' });