From 3c6e651166259643669b9f527ed5d142074efdd3 Mon Sep 17 00:00:00 2001 From: admin Date: Thu, 1 Oct 2026 00:44:04 +0300 Subject: [PATCH] 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. --- src/qbirr/__init__.py | 57 ++++++++++++++++++++++++++++++++++--------- 1 file changed, 45 insertions(+), 12 deletions(-) diff --git a/src/qbirr/__init__.py b/src/qbirr/__init__.py index 9cf174e..c5c065e 100644 --- a/src/qbirr/__init__.py +++ b/src/qbirr/__init__.py @@ -41,6 +41,49 @@ class VerifyResult: amount: float error: str + #: 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: float = 0.0 + + #: True means "we could not reach the bank", so ``verified`` is False because + #: the payment was NOT CHECKED YET -- not because it is invalid. Retry, or + #: fall back to manual review. Never reject an order on this. + retryable: bool = False + + #: 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). ``None`` on success. + code: Optional[str] = None + + #: 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: + #: a ``verified=True`` with ``"none"`` means the reference exists and the + #: amount matches, but says nothing about who received the money. + receiver_source: Optional[str] = None + + #: True only on sandbox (``TEST-...``) responses. + sandbox: bool = False + + @classmethod + def from_payload(cls, data: Dict[str, Any]) -> "VerifyResult": + """Fill in the additive fields so a caller never sees a missing value, + including against an API build that predates them.""" + return cls( + verified=bool(data.get("verified")), + payer=str(data.get("payer") or ""), + amount=float(data.get("amount") or 0), + error=str(data.get("error") or ""), + paid_amount=float(data.get("paid_amount") or 0), + retryable=bool(data.get("retryable")), + code=data.get("code") or None, + receiver_source=data.get("receiver_source") or None, + sandbox=bool(data.get("sandbox")), + ) + @dataclass class UsageStatus: @@ -101,12 +144,7 @@ class Qbirr: body["receiver_account"] = receiver_account data = self._request("POST", "/api/v1/verify", json=body) - return VerifyResult( - verified=bool(data.get("verified")), - payer=str(data.get("payer") or ""), - amount=float(data.get("amount") or 0), - error=str(data.get("error") or ""), - ) + return VerifyResult.from_payload(data) def verify_upload( self, @@ -154,12 +192,7 @@ class Qbirr: msg = data.get("error") if isinstance(data, dict) else f"HTTP {resp.status_code}" raise QbirrError(str(msg), status=resp.status_code, body=data) - return VerifyResult( - verified=bool(data.get("verified")), - payer=str(data.get("payer") or ""), - amount=float(data.get("amount") or 0), - error=str(data.get("error") or ""), - ) + return VerifyResult.from_payload(data) def usage(self) -> UsageStatus: data = self._request("GET", "/api/v1/usage")