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:
+45
-12
@@ -41,6 +41,49 @@ class VerifyResult:
|
|||||||
amount: float
|
amount: float
|
||||||
error: str
|
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
|
@dataclass
|
||||||
class UsageStatus:
|
class UsageStatus:
|
||||||
@@ -101,12 +144,7 @@ class Qbirr:
|
|||||||
body["receiver_account"] = receiver_account
|
body["receiver_account"] = receiver_account
|
||||||
|
|
||||||
data = self._request("POST", "/api/v1/verify", json=body)
|
data = self._request("POST", "/api/v1/verify", json=body)
|
||||||
return VerifyResult(
|
return VerifyResult.from_payload(data)
|
||||||
verified=bool(data.get("verified")),
|
|
||||||
payer=str(data.get("payer") or ""),
|
|
||||||
amount=float(data.get("amount") or 0),
|
|
||||||
error=str(data.get("error") or ""),
|
|
||||||
)
|
|
||||||
|
|
||||||
def verify_upload(
|
def verify_upload(
|
||||||
self,
|
self,
|
||||||
@@ -154,12 +192,7 @@ class Qbirr:
|
|||||||
msg = data.get("error") if isinstance(data, dict) else f"HTTP {resp.status_code}"
|
msg = data.get("error") if isinstance(data, dict) else f"HTTP {resp.status_code}"
|
||||||
raise QbirrError(str(msg), status=resp.status_code, body=data)
|
raise QbirrError(str(msg), status=resp.status_code, body=data)
|
||||||
|
|
||||||
return VerifyResult(
|
return VerifyResult.from_payload(data)
|
||||||
verified=bool(data.get("verified")),
|
|
||||||
payer=str(data.get("payer") or ""),
|
|
||||||
amount=float(data.get("amount") or 0),
|
|
||||||
error=str(data.get("error") or ""),
|
|
||||||
)
|
|
||||||
|
|
||||||
def usage(self) -> UsageStatus:
|
def usage(self) -> UsageStatus:
|
||||||
data = self._request("GET", "/api/v1/usage")
|
data = self._request("GET", "/api/v1/usage")
|
||||||
|
|||||||
Reference in New Issue
Block a user