cheki 0.1.0__py3-none-any.whl

cheki-0.1.0.dist-info/METADATA

@@ -0,0 +1,409 @@
+Metadata-Version: 2.4
+Name: cheki
+Version: 0.1.0
+Summary: Free, open-source Ethiopian bank/wallet receipt verification. Reverse-engineered public endpoints.
+Project-URL: Homepage, https://github.com/1RB/cheki
+Project-URL: Repository, https://github.com/1RB/cheki
+Project-URL: Issues, https://github.com/1RB/cheki/issues
+Author: 1RB
+License: MIT
+Keywords: bank,cbe,ethiopia,receipt,telebirr,verification
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Requires-Dist: beautifulsoup4>=4.11.0
+Requires-Dist: pdfplumber>=0.9.0
+Requires-Dist: requests>=2.28.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: reportlab>=4.0.0; extra == 'dev'
+Requires-Dist: responses>=0.23.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# cheki Python SDK
+
+Free, open-source **Ethiopian bank/wallet receipt verification** for Python.
+
+cheki verifies that a payment receipt is real by fetching it directly from the
+bank's own public receipt endpoint — no API keys, no paywalls, no scraping with
+Selenium. This SDK mirrors the [cheki](https://github.com/1RB/cheki) project's
+other official SDKs (TypeScript, Go, PHP, Dart).
+
+## Two modes
+
+The SDK offers two complementary ways to verify receipts:
+
+| Mode | When to use | How it works |
+| --- | --- | --- |
+| **API client** (recommended) | Production apps, servers, anything that wants reliability | Calls the hosted cheki REST API, which handles geo-blocking, QR decryption, PDF parsing, and bank-endpoint rotation for you. |
+| **Direct verification** (advanced) | Self-hosting, no external dependency, research | Fetches bank endpoints *directly* from your machine. No round-trip to cheki, but geo-blocked banks (telebirr, M-Pesa) will fail outside Ethiopia. |
+
+Both are importable from the top-level package:
+
+```python
+from ethio_receipt_verify import ChekiClient, verify, supported_banks
+```
+
+---
+
+## Quick start — API client
+
+```python
+from ethio_receipt_verify import ChekiClient
+
+cheki = ChekiClient()  # uses https://cheki-pi.vercel.app by default
+
+# CBE requires the receiving account number
+result = cheki.verify("cbe", "FT26140P01YB", account_number="1000560536171")
+
+if result.is_verified:
+    print(f"{result.sender_name} sent {result.amount} {result.currency}")
+    print(f"to {result.receiver_name} on {result.date}")
+else:
+    print(f"Not verified: {result.error}")
+```
+
+### Batch verification
+
+Verify up to 50 receipts in a single request:
+
+```python
+results = cheki.verify_batch([
+    {"bank": "cbe", "reference": "FT26140P01YB", "accountNumber": "1000560536171"},
+    {"bank": "telebirr", "reference": "DET8FJGUJ4"},
+    {"bank": "dashen", "reference": "B22WDTI261620001"},
+])
+
+print(f"{results.verified}/{results.total} verified")
+for r in results.results:
+    print(r.reference, r.is_verified, r.error)
+```
+
+### Discover supported banks
+
+```python
+for bank in cheki.get_banks():
+    print(f"{bank.code:<12} {bank.name}  [{bank.status}]")
+```
+
+### Health check
+
+```python
+health = cheki.get_health()
+print(health.status)        # "ok"
+for check in health.checks:
+    print(f"  {check.name}: {check.status} ({check.latency_ms}ms)")
+```
+
+### Context manager
+
+`ChekiClient` reuses a connection pool and can be used as a context manager:
+
+```python
+with ChekiClient(timeout=10, max_retries=5) as cheki:
+    result = cheki.verify("cbe", "FT26140P01YB", account_number="1000560536171")
+```
+
+---
+
+## Quick start — Direct verification (advanced)
+
+Direct verification fetches the bank endpoint from *your* machine. It needs no
+cheki server but is subject to geo-blocking and bank-side changes.
+
+```python
+from ethio_receipt_verify import verify, supported_banks
+
+# CBE needs the full receiving account number
+result = verify("cbe", "FT26140P01YB", account_number="1000560536171")
+
+print(result.status)          # VerificationStatus.VERIFIED
+print(result.exists)          # True
+print(result.amount)          # 20000.0
+print(result.sender_name)
+
+# telebirr / M-Pesa only work from Ethiopian IP addresses
+print(supported_banks())
+```
+
+Direct verification returns a `VerificationResult` (different from the API
+client's `ClientVerifyResult`). See the [API reference](#api-reference) below.
+
+---
+
+## Installation
+
+```bash
+pip install cheki
+```
+
+From source (development):
+
+```bash
+git clone https://github.com/1RB/cheki.git
+cd cheki/python
+pip install -e ".[dev]"
+```
+
+Dependencies: `requests`, `beautifulsoup4`, `pdfplumber` (the latter two are only
+needed for direct verification of PDF/HTML receipts).
+
+---
+
+## API reference
+
+### `ChekiClient`
+
+```python
+ChekiClient(
+    base_url="https://cheki-pi.vercel.app",
+    api_key=None,
+    timeout=30,
+    max_retries=3,
+    session=None,
+    user_agent=None,
+)
+```
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `base_url` | `str` | `https://cheki-pi.vercel.app` | cheki API root URL. |
+| `api_key` | `str \| None` | `None` | Optional bearer token. The public API does not require one. |
+| `timeout` | `float` | `30` | Per-request timeout in seconds. |
+| `max_retries` | `int` | `3` | Retries on HTTP 408/429/5xx (in addition to the first attempt). |
+| `session` | `requests.Session \| None` | `None` | Reuse a custom session (connection pool, proxies, etc.). |
+| `user_agent` | `str \| None` | auto | `User-Agent` header value. |
+
+#### Methods
+
+##### `verify(bank, reference, account_number=None, phone_number=None, qr_data=None) -> ClientVerifyResult`
+
+Verify a single receipt.
+
+##### `verify_batch(receipts) -> ClientBatchResult`
+
+Verify up to 50 receipts. Each receipt is a dict with `bank`, `reference`, and
+optional `accountNumber` / `phoneNumber` / `qrData`. Results are returned in
+input order with computed `total` / `verified` / `failed` counts.
+
+##### `get_banks() -> list[ClientBankInfo]`
+
+List supported banks/wallets.
+
+##### `get_health() -> ClientHealthStatus`
+
+Check service health (per-bank reachability).
+
+##### `get_receipt_url(bank, reference, account_number=None) -> str`
+
+Build a direct receipt-viewer URL (no network request).
+
+##### `close()`
+
+Close the underlying HTTP session.
+
+### Response types
+
+#### `ClientVerifyResult`
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `success` | `bool` | HTTP-level success. |
+| `verified` | `bool \| None` | Whether the receipt is legitimate. |
+| `bank`, `bank_code`, `reference` | `str \| None` | Identifiers. |
+| `source_url` | `str \| None` | Where the receipt was fetched from. |
+| `sender_name`, `sender_account` | `str \| None` | Sender details. |
+| `receiver_name`, `receiver_account` | `str \| None` | Receiver details. |
+| `amount`, `currency` | `float \| None`, `str \| None` | Payment amount. |
+| `date` | `str \| None` | Transaction date (as reported by the bank). |
+| `branch`, `reason` | `str \| None` | Extra metadata. |
+| `duration_ms` | `int \| None` | Server-side processing time. |
+| `invoice_number`, `transaction_status` | `str \| None` | Wallet-specific. |
+| `settled_amount`, `stamp_duty`, `discount_amount` | `float \| None` | Wallet fees. |
+| `service_fee`, `service_fee_vat`, `total_paid` | `float \| None` | Wallet fees. |
+| `amount_in_words`, `payment_mode`, `payment_channel` | `str \| None` | Wallet metadata. |
+| `bank_account_number`, `bank_account_name` | `str \| None` | Wallet metadata. |
+| `error` | `str \| None` | Error message on failure. |
+| `fallback_url` | `str \| None` | Direct URL for geo-blocked banks. |
+| `index` | `int \| None` | Position within a batch. |
+| `raw` | `dict` | The unparsed API payload. |
+
+Helper: `result.is_verified` → `True` when `success` and `verified` are both true.
+
+#### `ClientBatchResult`
+
+`success`, `total`, `verified`, `failed`, `results` (list of
+`ClientVerifyResult`), `error`, `raw`.
+
+#### `ClientBankInfo`
+
+`code`, `name`, `swift`, `type`, `status`, `requires_account`,
+`account_digits`, `requires_phone`, `endpoint`, `color`, `initials`, `raw`.
+Helper: `bank.is_live`.
+
+#### `ClientHealthStatus`
+
+`success`, `status`, `version`, `timestamp`, `checks` (list of
+`ClientHealthCheck`), `raw`. Helper: `health.is_ok`.
+
+#### `ClientHealthCheck`
+
+`name`, `status`, `latency_ms`, `raw`.
+
+### Direct verification
+
+#### `verify(bank, reference, **kwargs) -> VerificationResult`
+
+Fetch and parse a receipt directly from the bank endpoint.
+
+- `cbe`, `boa`: pass `account_number=` (full receiving account).
+- `cbebirr`: pass `phone_number=` (payer phone, `2519XXXXXXXXX`).
+
+Returns a `VerificationResult` with `status` (`VerificationStatus`), `exists`,
+`amount`, `sender_name`, `receiver_name`, `transaction_date`, `source_url`, etc.
+
+#### `supported_banks() -> dict[str, str]`
+
+Map of bank code → human name for the banks with direct verifiers.
+
+---
+
+## Error handling
+
+### API client errors
+
+All API client errors derive from `ChekiClientError`:
+
+```python
+from ethio_receipt_verify import (
+    ChekiClient, ChekiClientError, ChekiAPIError, ChekiNetworkError, ChekiTimeoutError,
+)
+
+cheki = ChekiClient()
+try:
+    result = cheki.verify("cbe", "FT26140P01YB", account_number="1000560536171")
+except ChekiTimeoutError as exc:
+    print("Request timed out:", exc)
+except ChekiNetworkError as exc:
+    print("Network error:", exc)
+except ChekiAPIError as exc:
+    print(f"API error (HTTP {exc.status_code}):", exc.message)
+except ChekiClientError as exc:
+    print("Client error:", exc)
+```
+
+| Error | Meaning |
+| --- | --- |
+| `ChekiAPIError` | Non-2xx API response. Carries `status_code`, `message`, `body`. |
+| `ChekiNetworkError` | Connection failure. |
+| `ChekiTimeoutError` | Request timed out (subclass of `ChekiNetworkError`). |
+
+> **Note:** a verification that *finds no receipt* is **not** an error — the API
+> returns `success: false` with an `error` message in the `ClientVerifyResult`.
+> Exceptions are reserved for transport/server failures.
+
+### Direct verification errors
+
+```python
+from ethio_receipt_verify import verify
+from ethio_receipt_verify.errors import (
+    VerificationError, ReceiptNotFoundError, UpstreamError, UnsupportedBankError,
+)
+```
+
+| Error | Meaning |
+| --- | --- |
+| `UnsupportedBankError` | The bank code is not supported. |
+| `ReceiptNotFoundError` | The bank returned a "not found" response. |
+| `UpstreamError` | The bank endpoint is unreachable or returned an error. |
+
+### Retries
+
+`ChekiClient` automatically retries on HTTP `408`, `429`, and `5xx` using
+exponential backoff with full jitter (up to `max_retries` extra attempts). A
+`Retry-After` header, when present, is honored. Network and timeout errors are
+also retried.
+
+---
+
+## CLI
+
+Install the package to get the `ethio-verify` command:
+
+```bash
+# API client (recommended)
+ethio-verify cbe FT26140P01YB --account 1000560536171 --api
+ethio-verify telebirr DET8FJGUJ4 --api --json
+
+# Direct verification (advanced)
+ethio-verify cbe FT26140P01YB --account 1000560536171
+
+# Service health & supported banks (via API)
+ethio-verify --health
+ethio-verify --list-banks --api
+```
+
+### Flags
+
+| Flag | Description |
+| --- | --- |
+| `bank` | Bank/wallet code (e.g. `cbe`, `telebirr`, `boa`, `mpesa`). |
+| `reference` | Transaction reference number. |
+| `--account` | Receiving account number (required for cbe, boa). |
+| `--phone` | Payer phone number (required for cbebirr). |
+| `--qr` | Raw QR payload (Bank of Abyssinia inter-bank receipts). |
+| `--api` | Use the hosted cheki REST API instead of direct verification. |
+| `--base-url` | cheki API base URL (default: `https://cheki-pi.vercel.app`). |
+| `--api-key` | Optional bearer token. |
+| `--timeout` | Per-request timeout in seconds (API mode, default: 30). |
+| `--json` | Output raw JSON. |
+| `--list-banks` | List supported banks and exit. |
+| `--health` | Check cheki API health and exit (implies `--api`). |
+
+---
+
+## Configuration
+
+### Custom base URL / self-hosting
+
+```python
+cheki = ChekiClient(base_url="https://cheki.my-server.com")
+```
+
+### Proxies & custom session
+
+```python
+import requests
+
+session = requests.Session()
+session.proxies = {"https": "http://proxy.local:8080"}
+cheki = ChekiClient(session=session)
+```
+
+### Timeouts & retries
+
+```python
+cheki = ChekiClient(timeout=10, max_retries=5)
+```
+
+---
+
+## Supported banks
+
+cbe, telebirr, boa, mpesa, dashen, zemen, cbebirr, siinqee, kaafiebirr (and
+more — run `cheki.get_banks()` or `ethio-verify --list-banks --api` for the
+current list). Availability depends on the bank endpoint's status and
+geo-restrictions.
+
+---
+
+## License
+
+MIT © [1RB](https://github.com/1RB)

cheki-0.1.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+ethio_receipt_verify/__init__.py,sha256=_jQnEt2TCMpGHg2_dKSXq36FVqiQqSip5xY78mCfy-g,1466
+ethio_receipt_verify/cli.py,sha256=5GWn2ms7iDywI1P3h5sDZnBit1UroLSiXrxndJHQGHA,9226
+ethio_receipt_verify/client.py,sha256=kL4_niQdeZ6FSH49r4nk_xlKU-JkrYfR_jZsYY-s-NU,15813
+ethio_receipt_verify/client_types.py,sha256=mqB6tw5053vOawLXH5UPvKidqLLRJlx7W1Vh9oh6igg,14629
+ethio_receipt_verify/errors.py,sha256=c2A5TWbD98fp2tUe77QVz57_VhaPWKgfJYEZss8Usi8,407
+ethio_receipt_verify/registry.py,sha256=UWgQiKzHFopjGRmGQXZAmMAEtXhzghguHc-37ry5BgY,929
+ethio_receipt_verify/result.py,sha256=YqGT7dAxxHbcVUcAA3wmntZkfOTzw7knPujrDFKxi0g,1491
+ethio_receipt_verify/banks/__init__.py,sha256=D3VbGX-yYSxcwz6UwLWOIfHShpTnMmnbT1oU5Y5WatQ,1099
+ethio_receipt_verify/banks/awash.py,sha256=BBwk_wZjdwS-4UErDldAipztc7Le4dl1p7cz7M_6HYw,1967
+ethio_receipt_verify/banks/base.py,sha256=5IytWjyb_69SVfVCbjpwNVYikKvIfAVsf4QukmzRzdY,895
+ethio_receipt_verify/banks/boa.py,sha256=Cku7iXnfkY3sFzhb8eK7ul_FlYHh1H1AK1SigFduIKA,3235
+ethio_receipt_verify/banks/cbe.py,sha256=EclLuMIjGbKSMn7WwAQMWywEgsYg-l0dmHMkqHI81ns,4215
+ethio_receipt_verify/banks/cbebirr.py,sha256=rQqLh_vstvp4iKxA0jSgh7v-xcXGqw9ljVXP2cXIbvg,1783
+ethio_receipt_verify/banks/dashen.py,sha256=UmfpvjWzQW2zmUg2qCQYmjYpxQEI6cBIvJNrNj2l9AE,1669
+ethio_receipt_verify/banks/kaafiebirr.py,sha256=M8xMGd4JvKXX9SIxzz0-ahPHbAylqjjUx2RMz8MYLlA,749
+ethio_receipt_verify/banks/mpesa.py,sha256=A8ZT_90zzYxrJDeZrCzUEnZSEN3TYagTZnp0pbROqbo,2624
+ethio_receipt_verify/banks/siinqee.py,sha256=zUZ2hRhYzc2OER5euwSONba04TIcmgB4VLie7Y0dMx0,746
+ethio_receipt_verify/banks/telebirr.py,sha256=i0wjqI9W68QM8DZp62NDOSIQJl_cyQ2xWTIdpYM1Ers,3570
+ethio_receipt_verify/banks/zemen.py,sha256=fQAWiuZV_L6aERu2dQmsTnozDNGbSPHjPSOc_TD8_pc,1749
+cheki-0.1.0.dist-info/METADATA,sha256=VdNqmuJsGjY1jTFxuwB7_FfYG6JvkNTgbSe9e390XHQ,12795
+cheki-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+cheki-0.1.0.dist-info/entry_points.txt,sha256=DQsgi_8ckpUP5oOKGfVANUb-0GpaJmXXffK6GIK8FZM,63
+cheki-0.1.0.dist-info/RECORD,,

cheki-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

cheki-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ethio-verify = ethio_receipt_verify.cli:main

ethio_receipt_verify/__init__.py

@@ -0,0 +1,52 @@
+"""Free, open-source Ethiopian bank/wallet receipt verification.
+
+cheki offers two complementary verification modes:
+
+1. **API client** — :class:`ChekiClient` wraps the hosted cheki REST API
+   (https://cheki-pi.vercel.app). This is the simplest path and matches
+   the other cheki SDKs.
+
+2. **Direct verification** — :func:`verify` fetches bank endpoints
+   directly from your machine (advanced; subject to geo-blocking).
+
+Both are importable from the top-level package::
+
+    from ethio_receipt_verify import ChekiClient, verify, supported_banks
+"""
+
+from ethio_receipt_verify.result import VerificationResult, VerificationStatus
+from ethio_receipt_verify.registry import verify, supported_banks
+from ethio_receipt_verify.client import ChekiClient, DEFAULT_BASE_URL
+from ethio_receipt_verify.client_types import (
+    ChekiClientError,
+    ChekiAPIError,
+    ChekiNetworkError,
+    ChekiTimeoutError,
+    ClientVerifyResult,
+    ClientBatchResult,
+    ClientBankInfo,
+    ClientHealthCheck,
+    ClientHealthStatus,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Direct verification (advanced)
+    "VerificationResult",
+    "VerificationStatus",
+    "verify",
+    "supported_banks",
+    # API client
+    "ChekiClient",
+    "DEFAULT_BASE_URL",
+    "ChekiClientError",
+    "ChekiAPIError",
+    "ChekiNetworkError",
+    "ChekiTimeoutError",
+    "ClientVerifyResult",
+    "ClientBatchResult",
+    "ClientBankInfo",
+    "ClientHealthCheck",
+    "ClientHealthStatus",
+]

ethio_receipt_verify/banks/__init__.py

@@ -0,0 +1,28 @@
+"""Bank/wallet specific verifiers."""
+
+from ethio_receipt_verify.banks.base import BankVerifier
+from ethio_receipt_verify.banks.cbe import CBEVerifier
+from ethio_receipt_verify.banks.telebirr import TelebirrVerifier
+from ethio_receipt_verify.banks.boa import BOAVerifier
+from ethio_receipt_verify.banks.mpesa import MPesaVerifier
+from ethio_receipt_verify.banks.zemen import ZemenVerifier
+from ethio_receipt_verify.banks.dashen import DashenVerifier
+from ethio_receipt_verify.banks.awash import AwashVerifier
+from ethio_receipt_verify.banks.cbebirr import CBEBirrVerifier
+from ethio_receipt_verify.banks.siinqee import SiinqeeVerifier
+from ethio_receipt_verify.banks.kaafiebirr import KaafiEbirrbankVerifier
+
+VERIFIERS: dict[str, type[BankVerifier]] = {
+    "cbe": CBEVerifier,
+    "telebirr": TelebirrVerifier,
+    "boa": BOAVerifier,
+    "mpesa": MPesaVerifier,
+    "zemen": ZemenVerifier,
+    "dashen": DashenVerifier,
+    "awash": AwashVerifier,
+    "cbebirr": CBEBirrVerifier,
+    "siinqee": SiinqeeVerifier,
+    "kaafiebirr": KaafiEbirrbankVerifier,
+}
+
+__all__ = ["VERIFIERS", "BankVerifier"]

ethio_receipt_verify/banks/awash.py

@@ -0,0 +1,48 @@
+import requests
+
+from ethio_receipt_verify.banks.base import BankVerifier
+from ethio_receipt_verify.errors import ReceiptNotFoundError, UpstreamError
+from ethio_receipt_verify.result import VerificationResult, VerificationStatus
+
+
+class AwashVerifier(BankVerifier):
+    """Awash Bank receipt verifier.
+
+    Known public endpoint (from check.et):
+        https://awashpay.awashbank.com:8225/-<REFERENCE>
+    Port 8225 currently returns 403; port 443 returns a generic landing page.
+    The exact working URL format is still unknown.
+    """
+
+    BANK_CODE = "awash"
+    BANK_NAME = "Awash Bank"
+
+    def verify(self, reference: str, **kwargs: object) -> VerificationResult:
+        urls = [
+            f"https://awashpay.awashbank.com:8225/-{reference}",
+            f"https://awashpay.awashbank.com/{reference}",
+            f"https://awashpay.awashbank.com/receipt/{reference}",
+        ]
+        last_exc: Exception | None = None
+        for url in urls:
+            try:
+                resp = self._get(url, verify=False)
+            except requests.RequestException as exc:
+                last_exc = exc
+                continue
+            if resp.status_code == 200 and "Invalid receipt id" not in resp.text and "Servicecops" not in resp.text:
+                return VerificationResult(
+                    bank=self.BANK_CODE,
+                    reference=reference,
+                    status=VerificationStatus.VERIFIED,
+                    exists=True,
+                    source_url=url,
+                    raw={"response": resp.text[:2000]},
+                    message="Awash receipt fetched. Detailed parsing is not yet implemented.",
+                )
+            if resp.status_code == 404 or "Invalid receipt id" in resp.text:
+                raise ReceiptNotFoundError("Awash did not find a receipt for this reference.")
+
+        raise UpstreamError(
+            f"Awash receipt endpoint could not be reached. Last error: {last_exc}"
+        )

ethio_receipt_verify/banks/base.py

@@ -0,0 +1,29 @@
+from abc import ABC, abstractmethod
+
+import requests
+
+from ethio_receipt_verify.result import VerificationResult
+
+
+class BankVerifier(ABC):
+    """Base class for bank/wallet receipt verifiers."""
+
+    BANK_CODE: str
+    BANK_NAME: str
+
+    def __init__(self, session: requests.Session | None = None):
+        self.session = session or requests.Session()
+        self.session.headers.update({
+            "User-Agent": "Mozilla/5.0 (compatible; ethio-receipt-verify/0.1.0)"
+        })
+
+    @abstractmethod
+    def verify(self, reference: str, **kwargs: object) -> VerificationResult:
+        """Verify a receipt by its reference number."""
+        ...
+
+    def _get(self, url: str, **kwargs) -> requests.Response:
+        return self.session.get(url, timeout=30, **kwargs)
+
+    def _post(self, url: str, **kwargs) -> requests.Response:
+        return self.session.post(url, timeout=30, **kwargs)

ethio_receipt_verify/banks/boa.py

@@ -0,0 +1,89 @@
+import re
+from datetime import datetime
+
+import requests
+
+from ethio_receipt_verify.banks.base import BankVerifier
+from ethio_receipt_verify.errors import ReceiptNotFoundError, UpstreamError
+from ethio_receipt_verify.result import VerificationResult, VerificationStatus
+
+
+class BOAVerifier(BankVerifier):
+    """Bank of Abyssinia receipt verifier.
+
+    BOA serves a SPA receipt page, but the data comes from a public T24 API:
+        https://cs.bankofabyssinia.com/api/onlineSlip/getDetails/?id=<trx_id>
+    where trx_id is the transaction reference concatenated with the last 5
+    digits of the receiver account.
+    """
+
+    BANK_CODE = "boa"
+    BANK_NAME = "Bank of Abyssinia"
+
+    def verify(self, reference: str, **kwargs: object) -> VerificationResult:
+        account_number = str(kwargs.get("account_number", "")).replace(" ", "")
+        if not account_number or len(account_number) < 5:
+            raise ValueError(
+                "BOA verification requires the full receiving account_number (at least 5 digits)."
+            )
+        suffix = account_number[-5:]
+        trx_id = f"{reference}{suffix}"
+        url = f"https://cs.bankofabyssinia.com/api/onlineSlip/getDetails/?id={trx_id}"
+
+        try:
+            resp = self._get(url)
+        except requests.RequestException as exc:
+            raise UpstreamError(f"BOA receipt endpoint unreachable: {exc}") from exc
+
+        if resp.status_code != 200:
+            raise UpstreamError(f"BOA returned status {resp.status_code}.")
+
+        try:
+            payload = resp.json()
+        except ValueError as exc:
+            raise UpstreamError("BOA returned non-JSON response.") from exc
+
+        body = payload.get("body", [])
+        if not body or body[0].get("Payer's Name") == "Invalid reference number":
+            raise ReceiptNotFoundError(
+                "BOA did not find a transaction for this reference and account suffix."
+            )
+
+        row = body[0]
+        parsed = self._parse_row(row)
+        parsed["source_url"] = url
+        parsed["reference"] = reference
+        parsed["bank"] = self.BANK_CODE
+        parsed["raw"] = payload
+        return VerificationResult(
+            status=VerificationStatus.VERIFIED,
+            exists=True,
+            **parsed,
+        )
+
+    def _parse_row(self, row: dict) -> dict:
+        data: dict = {}
+
+        data["sender_name"] = row.get("Source Account Name")
+        data["sender_account"] = row.get("Source Account")
+        data["receiver_name"] = row.get("Receiver's Name")
+        data["receiver_account"] = row.get("Receiver's Account")
+        data["currency"] = row.get("currency", "ETB")
+
+        amount_raw = row.get("Transferred Amount", "")
+        if amount_raw:
+            try:
+                data["amount"] = float(re.sub(r"[^0-9.]", "", str(amount_raw)))
+            except ValueError:
+                pass
+
+        date_raw = row.get("Transaction Date", "")
+        if date_raw:
+            for fmt in ("%d-%b-%Y", "%d/%m/%Y", "%Y-%m-%d", "%d-%m-%Y %H:%M:%S"):
+                try:
+                    data["transaction_date"] = datetime.strptime(date_raw, fmt)
+                    break
+                except ValueError:
+                    continue
+
+        return data