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;
/** Required for CBE and Bank of Abyssinia. Ignored for other providers. */
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 {
@@ -86,6 +90,8 @@ export interface VerifyResult {
* about who received the money.
*/
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. */
sandbox?: boolean;
}
@@ -104,6 +110,7 @@ function normalise(r: Partial<VerifyResult> & { verified?: boolean }): VerifyRes
retryable: Boolean(r.retryable),
code: r.code ?? null,
receiver_source: r.receiver_source ?? null,
payer_error: r.payer_error ?? null,
...(r.sandbox ? { sandbox: true } : {}),
};
}
@@ -172,6 +179,8 @@ export class Qbirr {
receiver_name: req.receiverName,
};
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));
}
@@ -197,6 +206,10 @@ export class Qbirr {
amount: number;
receiverName: 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;
filename?: string;
contentType?: string;
@@ -206,6 +219,8 @@ export class Qbirr {
form.append('amount', String(opts.amount));
form.append('receiver_name', opts.receiverName);
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
? opts.file
: new Blob([opts.file as unknown as BlobPart], { type: opts.contentType || 'application/octet-stream' });