tx-verify 0.1.0__py3-none-any.whl

tx_verify/__init__.py

@@ -0,0 +1,39 @@
+"""Payment Verification API - Python library for verifying Ethiopian payment transactions."""
+
+from tx_verify.services.verify_abyssinia import AbyssiniaReceipt, verify_abyssinia
+from tx_verify.services.verify_cbe import VerifyResult, verify_cbe
+from tx_verify.services.verify_cbe_birr import CBEBirrReceipt, verify_cbe_birr
+from tx_verify.services.verify_dashen import DashenVerifyResult, verify_dashen
+from tx_verify.services.verify_image import verify_image
+from tx_verify.services.verify_mpesa import MpesaVerifyResult, verify_mpesa
+from tx_verify.services.verify_telebirr import (
+    TelebirrReceipt,
+    TelebirrVerificationError,
+    verify_telebirr,
+)
+from tx_verify.services.verify_universal import verify_universal
+from tx_verify.utils.error_handler import AppError, ErrorType
+from tx_verify.utils.logger import logger
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "verify_cbe",
+    "verify_telebirr",
+    "verify_dashen",
+    "verify_abyssinia",
+    "verify_cbe_birr",
+    "verify_mpesa",
+    "verify_image",
+    "verify_universal",
+    "VerifyResult",
+    "TelebirrReceipt",
+    "TelebirrVerificationError",
+    "DashenVerifyResult",
+    "AbyssiniaReceipt",
+    "CBEBirrReceipt",
+    "MpesaVerifyResult",
+    "AppError",
+    "ErrorType",
+    "logger",
+]

tx_verify/services/verify_abyssinia.py

@@ -0,0 +1,156 @@
+"""Bank of Abyssinia payment verification service.
+
+Translated from src/services/verifyAbyssinia.ts
+"""
+
+from dataclasses import dataclass
+from datetime import datetime
+
+import httpx
+
+from tx_verify.services.verify_cbe import VerifyResult
+from tx_verify.utils.http_client import get_async_client
+from tx_verify.utils.logger import logger
+
+
+@dataclass
+class AbyssiniaReceipt:
+    """Raw receipt fields returned by the Abyssinia API."""
+
+    source_account_name: str = ""
+    vat: str = ""
+    transferred_amount_in_word: str = ""
+    address: str = ""
+    transaction_type: str = ""
+    service_charge: str = ""
+    source_account: str = ""
+    payment_reference: str = ""
+    tel: str = ""
+    payer_name: str = ""
+    narrative: str = ""
+    transferred_amount: str = ""
+    transaction_reference: str = ""
+    transaction_date: str = ""
+    total_amount_including_vat: str = ""
+
+
+async def verify_abyssinia(
+    reference: str, suffix: str = "", *, proxies: str | dict[str, str] | None = None
+) -> VerifyResult:
+    """Verify an Abyssinia bank transaction via their public API.
+
+    Args:
+        reference: Transaction reference (e.g. "FT23062669JJ")
+        suffix: Last 5 digits of the user's account (e.g. "90172")
+    """
+    try:
+        logger.info(
+            "\U0001f3e6 Starting Abyssinia verification for reference: %s with suffix: %s",
+            reference,
+            suffix,
+        )
+
+        api_url = (
+            f"https://cs.bankofabyssinia.com/api/onlineSlip/getDetails/?id={reference}{suffix}"
+        )
+        logger.info("\U0001f4e1 Fetching from URL: %s", api_url)
+
+        async with get_async_client(timeout=30.0, proxies=proxies) as client:
+            response = await client.get(
+                api_url,
+                headers={
+                    "User-Agent": (
+                        "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+                        "AppleWebKit/537.36 (KHTML, like Gecko) "
+                        "Chrome/91.0.4472.124 Safari/537.36"
+                    ),
+                    "Accept": "application/json, text/plain, */*",
+                    "Accept-Language": "en-US,en;q=0.9",
+                    "Cache-Control": "no-cache",
+                    "Pragma": "no-cache",
+                },
+            )
+
+        logger.info("\u2705 Successfully fetched response with status: %s", response.status_code)
+
+        json_data = response.json()
+
+        # Validate response structure
+        if (
+            not json_data
+            or "header" not in json_data
+            or "body" not in json_data
+            or not isinstance(json_data["body"], list)
+        ):
+            logger.error("\u274c Invalid response structure from Abyssinia API")
+            return VerifyResult(
+                success=False, error="Invalid response structure from Abyssinia API"
+            )
+
+        if json_data["header"].get("status") != "success":
+            status = json_data["header"].get("status")
+            logger.error("\u274c API returned error status: %s", status)
+            return VerifyResult(success=False, error=f"API returned error status: {status}")
+
+        if len(json_data["body"]) == 0:
+            logger.error("\u274c No transaction data found in response body")
+            return VerifyResult(success=False, error="No transaction data found in response body")
+
+        tx = json_data["body"][0]
+        logger.debug("\U0001f4cb Raw transaction data from API: %s", tx)
+
+        # Extract and parse amount
+        transferred_amount_str = (
+            tx.get("Transferred Amount") or tx.get("Total Amount including VAT") or ""
+        )
+        amount: float | None = None
+        if transferred_amount_str:
+            import re
+
+            cleaned = re.sub(r"[^\d.]", "", transferred_amount_str)
+            if cleaned:
+                amount = float(cleaned)
+
+        transaction_date_str = tx.get("Transaction Date") or ""
+        date: datetime | None = None
+        if transaction_date_str:
+            try:
+                date = datetime.fromisoformat(transaction_date_str)
+            except ValueError:
+                # Try other common formats
+                for fmt in ("%Y-%m-%d %H:%M:%S", "%d/%m/%Y %H:%M:%S", "%m/%d/%Y %H:%M:%S"):
+                    try:
+                        date = datetime.strptime(transaction_date_str, fmt)
+                        break
+                    except ValueError:
+                        continue
+
+        result = VerifyResult(
+            success=True,
+            payer=tx.get("Payer's Name") or tx.get("Source Account Name") or None,
+            payer_account=tx.get("Source Account") or tx.get("Payer's Account") or None,
+            receiver=tx.get("Receiver's Name") or tx.get("Beneficiary Name") or None,
+            receiver_account=tx.get("Receiver's Account") or tx.get("Beneficiary Account") or None,
+            amount=amount,
+            date=date,
+            reference=tx.get("Transaction Reference") or tx.get("Payment Reference") or None,
+            reason=tx.get("Narrative") or tx.get("Transaction Type") or None,
+        )
+
+        logger.info(
+            "\u2705 Successfully parsed Abyssinia receipt for reference: %s", result.reference
+        )
+
+        # Validate essential fields
+        if not result.reference or not result.amount:
+            logger.error("\u274c Missing essential fields in transaction data")
+            return VerifyResult(success=False, error="Missing essential fields in transaction data")
+
+        return result
+
+    except httpx.HTTPError as e:
+        logger.error("\u274c HTTP Error fetching Abyssinia receipt: %s", str(e))
+        return VerifyResult(success=False, error="Failed to verify Abyssinia transaction")
+    except Exception as e:
+        logger.error("\u274c Unexpected error in verify_abyssinia: %s", str(e))
+        return VerifyResult(success=False, error="Failed to verify Abyssinia transaction")

tx_verify/services/verify_cbe.py

@@ -0,0 +1,177 @@
+"""CBE (Commercial Bank of Ethiopia) payment verification service.
+
+Translated from src/services/verifyCBE.ts
+"""
+
+import io
+import re
+import ssl
+from dataclasses import dataclass
+from datetime import datetime
+
+from pypdf import PdfReader
+
+from tx_verify.utils.http_client import get_async_client
+from tx_verify.utils.logger import logger
+
+
+@dataclass
+class VerifyResult:
+    """Standard verification result used across multiple services."""
+
+    success: bool
+    payer: str | None = None
+    payer_account: str | None = None
+    receiver: str | None = None
+    receiver_account: str | None = None
+    amount: float | None = None
+    date: datetime | None = None
+    reference: str | None = None
+    reason: str | None = None
+    error: str | None = None
+
+
+def _title_case(s: str) -> str:
+    return s.title()
+
+
+def _make_ssl_context() -> ssl.SSLContext:
+    """Create an SSL context that does not verify certificates (mirrors rejectUnauthorized: false)."""
+    ctx = ssl.create_default_context()
+    ctx.check_hostname = False
+    ctx.verify_mode = ssl.CERT_NONE
+    return ctx
+
+
+async def verify_cbe(
+    reference: str, account_suffix: str = "", *, proxies: str | dict[str, str] | None = None
+) -> VerifyResult:
+    """Verify a CBE transaction by fetching and parsing its PDF receipt.
+
+    First attempts a direct HTTPS fetch; on failure would fall back to
+    a headless browser (not implemented in Python – returns error).
+    """
+    full_id = f"{reference}{account_suffix}"
+    url = f"https://apps.cbe.com.et:100/?id={full_id}"
+
+    try:
+        logger.info("\U0001f50e Attempting direct fetch: %s", url)
+        async with get_async_client(
+            verify=_make_ssl_context(), timeout=30.0, proxies=proxies
+        ) as client:
+            response = await client.get(
+                url,
+                headers={
+                    "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
+                    "Accept": "application/pdf",
+                },
+            )
+            response.raise_for_status()
+
+        logger.info("\u2705 Direct fetch success, parsing PDF")
+        return _parse_cbe_receipt(response.content)
+
+    except Exception as direct_err:
+        logger.warning("\u26a0\ufe0f Direct fetch failed: %s", str(direct_err))
+        # The TS version falls back to Puppeteer here.
+        # We do not bundle a headless browser; return the error.
+        return VerifyResult(
+            success=False,
+            error=f"Direct fetch failed: {direct_err}",
+        )
+
+
+def _parse_cbe_receipt(pdf_bytes: bytes) -> VerifyResult:
+    """Extract transaction fields from a CBE PDF receipt."""
+    try:
+        reader = PdfReader(io.BytesIO(pdf_bytes))
+        raw_text = ""
+        for page in reader.pages:
+            raw_text += page.extract_text() or ""
+
+        # Normalise whitespace
+        raw_text = re.sub(r"\s+", " ", raw_text).strip()
+
+        payer_match = re.search(r"Payer\s*:?\s*(.*?)\s+Account", raw_text, re.I)
+        payer_name = payer_match.group(1).strip() if payer_match else None
+
+        receiver_match = re.search(r"Receiver\s*:?\s*(.*?)\s+Account", raw_text, re.I)
+        receiver_name = receiver_match.group(1).strip() if receiver_match else None
+
+        account_matches = re.findall(r"Account\s*:?\s*([A-Z0-9]?\*{4}\d{4})", raw_text, re.I)
+        payer_account = account_matches[0] if len(account_matches) > 0 else None
+        receiver_account = account_matches[1] if len(account_matches) > 1 else None
+
+        reason_match = re.search(
+            r"Reason\s*/\s*Type of service\s*:?\s*(.*?)\s+Transferred Amount",
+            raw_text,
+            re.I,
+        )
+        reason = reason_match.group(1).strip() if reason_match else None
+
+        amount_match = re.search(r"Transferred Amount\s*:?\s*([\d,]+\.\d{2})\s*ETB", raw_text, re.I)
+        amount_text = amount_match.group(1) if amount_match else None
+
+        ref_match = re.search(
+            r"Reference No\.?\s*\(VAT Invoice No\)\s*:?\s*([A-Z0-9]+)",
+            raw_text,
+            re.I,
+        )
+        reference_val = ref_match.group(1).strip() if ref_match else None
+
+        date_match = re.search(r"Payment Date & Time\s*:?\s*([\d/,: ]+[APM]{2})", raw_text, re.I)
+        date_raw = date_match.group(1).strip() if date_match else None
+
+        amount = float(amount_text.replace(",", "")) if amount_text else None
+        date = _parse_date(date_raw) if date_raw else None
+
+        if payer_name:
+            payer_name = _title_case(payer_name)
+        if receiver_name:
+            receiver_name = _title_case(receiver_name)
+
+        if (
+            payer_name
+            and payer_account
+            and receiver_name
+            and receiver_account
+            and amount
+            and date
+            and reference_val
+        ):
+            return VerifyResult(
+                success=True,
+                payer=payer_name,
+                payer_account=payer_account,
+                receiver=receiver_name,
+                receiver_account=receiver_account,
+                amount=amount,
+                date=date,
+                reference=reference_val,
+                reason=reason,
+            )
+        else:
+            return VerifyResult(
+                success=False,
+                error="Could not extract all required fields from PDF.",
+            )
+
+    except Exception as e:
+        logger.error("\u274c PDF parsing failed: %s", str(e))
+        return VerifyResult(success=False, error="Error parsing PDF data")
+
+
+def _parse_date(raw: str) -> datetime | None:
+    """Best-effort parse of the date string from CBE receipts."""
+    for fmt in (
+        "%m/%d/%Y, %I:%M:%S %p",
+        "%m/%d/%Y %I:%M:%S %p",
+        "%d/%m/%Y, %I:%M:%S %p",
+        "%d/%m/%Y %I:%M:%S %p",
+        "%Y-%m-%d %H:%M:%S",
+    ):
+        try:
+            return datetime.strptime(raw, fmt)
+        except ValueError:
+            continue
+    return None

tx_verify/services/verify_cbe_birr.py

@@ -0,0 +1,318 @@
+"""CBE Birr payment verification service.
+
+Translated from src/services/verifyCBEBirr.ts
+"""
+
+import io
+import re
+from dataclasses import dataclass, field
+from datetime import datetime
+
+from pypdf import PdfReader
+
+from tx_verify.utils.http_client import get_async_client
+from tx_verify.utils.logger import logger
+
+
+@dataclass
+class CBEBirrReceipt:
+    """CBE Birr receipt data.
+
+    Core fields that appear consistently on every receipt.
+    Variable / optional fields are collected in ``meta``.
+    """
+
+    customer_name: str = ""
+    debit_account: str = ""
+    credit_account: str = ""
+    receiver_name: str = ""
+    order_id: str = ""
+    transaction_status: str = ""
+    receipt_number: str = ""
+    transaction_date: str = ""
+    amount: str = ""
+    paid_amount: str = ""
+    service_charge: str = ""
+    vat: str = ""
+    total_paid_amount: str = ""
+    payment_reason: str = ""
+    payment_channel: str = ""
+    meta: dict = field(default_factory=dict)
+
+
+@dataclass
+class CBEBirrError:
+    success: bool = False
+    error: str = ""
+
+
+async def verify_cbe_birr(
+    receipt_number: str, phone_number: str, *, proxies: str | dict[str, str] | None = None
+) -> CBEBirrReceipt | CBEBirrError:
+    """Verify a CBE Birr transaction by fetching and parsing its PDF receipt."""
+    try:
+        logger.info(
+            "[CBEBirr] Starting verification for receipt: %s, phone: %s",
+            receipt_number,
+            phone_number,
+        )
+
+        url = f"https://cbepay1.cbe.com.et/aureceipt?TID={receipt_number}&PH={phone_number}"
+        logger.info("[CBEBirr] Fetching PDF from: %s", url)
+
+        async with get_async_client(timeout=30.0, proxies=proxies) as client:
+            response = await client.get(
+                url,
+                headers={
+                    "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
+                },
+            )
+
+        logger.info("[CBEBirr] PDF response status: %s", response.status_code)
+        logger.info("[CBEBirr] PDF content length: %d bytes", len(response.content))
+
+        if response.status_code != 200:
+            logger.error("[CBEBirr] Failed to fetch PDF: HTTP %s", response.status_code)
+            return CBEBirrError(
+                success=False, error=f"Failed to fetch receipt: HTTP {response.status_code}"
+            )
+
+        # Parse PDF
+        reader = PdfReader(io.BytesIO(response.content))
+        pdf_text = ""
+        for page in reader.pages:
+            pdf_text += page.extract_text() or ""
+
+        logger.info("[CBEBirr] PDF text extracted (%d characters)", len(pdf_text))
+
+        receipt = _parse_cbe_birr_receipt(pdf_text)
+        if not receipt:
+            logger.error("[CBEBirr] Failed to parse receipt data from PDF")
+            return CBEBirrError(success=False, error="Failed to parse receipt data from PDF")
+
+        logger.info("[CBEBirr] Successfully parsed receipt data")
+        return receipt
+
+    except Exception as e:
+        logger.error("[CBEBirr] Error during verification: %s", e)
+        return CBEBirrError(
+            success=False,
+            error=str(e) if str(e) else "Unknown error occurred",
+        )
+
+
+def _parse_cbe_birr_receipt(pdf_text: str) -> CBEBirrReceipt | None:
+    """Parse CBE Birr receipt fields from extracted PDF text.
+
+    Uses a robust line-by-line scanner that works with the sparse
+    layout produced by pypdf.
+    """
+    try:
+        logger.info("[CBEBirr] Starting PDF text parsing...")
+
+        lines = [ln.strip() for ln in pdf_text.split("\n")]
+
+        # ------------------------------------------------------------------
+        # Labels that are guaranteed to be structural, never receipt values.
+        # ------------------------------------------------------------------
+        known_labels = {
+            "Commercial Bank of Ethiopia",
+            "VAT Invoice/ Customer Receipt",
+            "CBEBirr",
+            "Company Address & Other Information",
+            "Customer Information",
+            "Country:",
+            "City:",
+            "Address:",
+            "Postal code:",
+            "SWIFT Code:",
+            "Email:",
+            "Tel:",
+            "Fax:",
+            "TIN",
+            "VAT Invoice No:",
+            "VAT Registration No:",
+            "VAT Registration Date:",
+            "Customer Name:",
+            "Region:",
+            "Sub city:",
+            "Wereda/kebele:",
+            "TIN (TAX ID):",
+            "Transaction Information",
+            "Debit Account",
+            "Credit Account",
+            "Receiver Name",
+            "Order ID",
+            "Transaction Status",
+            "Reference",
+            "Transaction Details",
+            "Receipt Number",
+            "Transaction Date",
+            "Amount",
+            "Paid amount",
+            "Service Charge",
+            "VAT",
+            "Total Paid Amount",
+            "Total Amount in word",
+            "Payment Reason",
+            "Payment Channel",
+            "Branch:",
+            "Tip",
+            "The Bank you can always rely on!",
+            f"© {datetime.now().year} Commercial Bank of Ethiopia. All rights reserved",
+        }
+
+        def _next_value(start_idx: int) -> str:
+            """Return the next non-empty line that is not a known label."""
+            j = start_idx
+            while j < len(lines):
+                val = lines[j].strip()
+                if val and val not in known_labels:
+                    return val
+                j += 1
+            return ""
+
+        # ---- individual fields ------------------------------------------------
+        customer_name = ""
+        debit_account = ""
+        credit_account = ""
+        receiver_name = ""
+        order_id = ""
+        transaction_status = ""
+        reference = ""
+        receipt_number = ""
+        transaction_date = ""
+        amount = ""
+        paid_amount = ""
+        service_charge = ""
+        vat = ""
+        total_paid_amount = ""
+        total_amount_in_word = ""
+        payment_reason = ""
+        payment_channel = ""
+        branch = ""
+        tip = ""
+
+        i = 0
+        while i < len(lines):
+            line = lines[i]
+
+            # Customer name appears on the line immediately after "Sub city:"
+            if line == "Sub city:":
+                customer_name = _next_value(i + 1)
+
+            # Single-line labelled values
+            elif line == "Debit Account":
+                debit_account = _next_value(i + 1)
+
+            elif line == "Credit Account":
+                credit_account = _next_value(i + 1)
+
+            elif line == "Receiver Name":
+                receiver_name = _next_value(i + 1)
+
+            elif line == "Order ID":
+                order_id = _next_value(i + 1)
+
+            elif line == "Transaction Status":
+                transaction_status = _next_value(i + 1)
+
+            elif line == "Reference":
+                raw_ref = _next_value(i + 1)
+                reference = raw_ref.rstrip(":").strip() if raw_ref else ""
+
+            # Transaction Details block:
+            #  Receipt Number   Transaction Date   Amount
+            #  <receipt>        <date>             <amount>
+            #  <paid>           <service>          <vat>    <total>
+            #  Paid amount      Service Charge     VAT      Total Paid Amount
+            elif "Receipt Number" in line and "Transaction Date" in line and "Amount" in line:
+                j = i + 1
+                vals = []
+                while j < len(lines) and len(vals) < 3:
+                    val = lines[j].strip()
+                    if val and val not in known_labels:
+                        vals.append(val)
+                    j += 1
+                if len(vals) >= 3:
+                    receipt_number = vals[0]
+                    transaction_date = vals[1]
+                    amount = vals[2]
+
+                # Financial breakdown: 4 consecutive numeric values
+                fin_vals = []
+                while j < len(lines) and len(fin_vals) < 4:
+                    val = lines[j].strip()
+                    if re.match(r"^[\d.]+$", val):
+                        fin_vals.append(val)
+                    elif val in known_labels:
+                        break
+                    j += 1
+                if len(fin_vals) >= 4:
+                    paid_amount = fin_vals[0]
+                    service_charge = fin_vals[1]
+                    vat = fin_vals[2]
+                    total_paid_amount = fin_vals[3]
+
+            # Bottom block: Total Amount in word, Payment Reason, Payment Channel
+            # Each label is followed by a value. The values are collected in order.
+            elif line == "Total Amount in word":
+                j = i + 1
+                vals = []
+                while j < len(lines) and len(vals) < 3:
+                    val = lines[j].strip()
+                    if val and val not in known_labels:
+                        vals.append(val)
+                    j += 1
+                if len(vals) >= 3:
+                    total_amount_in_word = vals[0]
+                    payment_reason = vals[1]
+                    payment_channel = vals[2]
+
+            # Optional fields at the very bottom
+            elif line == "Branch:":
+                branch = _next_value(i + 1)
+
+            elif line == "Tip":
+                tip = _next_value(i + 1)
+
+            i += 1
+
+        # ---- validate we got the essentials ----------------------------------
+        if not customer_name and not receipt_number and not amount:
+            logger.warning("[CBEBirr] No essential fields found in PDF")
+            return None
+
+        # ---- assemble meta dict for optional/variable fields -----------------
+        meta: dict[str, str] = {}
+        if reference:
+            meta["reference"] = reference
+        if total_amount_in_word:
+            meta["total_amount_in_word"] = total_amount_in_word
+        if branch and branch != "0.00":
+            meta["branch"] = branch
+        if tip and tip != "0.00":
+            meta["tip"] = tip
+
+        return CBEBirrReceipt(
+            customer_name=customer_name,
+            debit_account=debit_account,
+            credit_account=credit_account,
+            receiver_name=receiver_name,
+            order_id=order_id,
+            transaction_status=transaction_status,
+            receipt_number=receipt_number,
+            transaction_date=transaction_date,
+            amount=amount,
+            paid_amount=paid_amount,
+            service_charge=service_charge,
+            vat=vat,
+            total_paid_amount=total_paid_amount,
+            payment_reason=payment_reason,
+            payment_channel=payment_channel,
+            meta=meta,
+        )
+
+    except Exception as e:
+        logger.error("[CBEBirr] Error parsing PDF text: %s", e)
+        return None