webirr 1.0.0__py3-none-any.whl

webirr/__init__.py

@@ -0,0 +1,25 @@
+"""Official Python client library for WeBirr Payment Gateway APIs."""
+
+from .client import WeBirrClient
+from .models import (
+    ApiResponse,
+    Bill,
+    BillResponse,
+    PaymentDetail,
+    PaymentResponse,
+    PaymentStatus,
+    Stat,
+)
+
+__all__ = [
+    "ApiResponse",
+    "Bill",
+    "BillResponse",
+    "PaymentDetail",
+    "PaymentResponse",
+    "PaymentStatus",
+    "Stat",
+    "WeBirrClient",
+]
+
+__version__ = "1.0.0"

webirr/client.py

@@ -0,0 +1,182 @@
+"""HTTP client for WeBirr Payment Gateway APIs."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Callable, TypeVar
+from urllib.parse import urljoin
+
+import requests
+
+from .models import (
+    ApiResponse,
+    Bill,
+    BillResponse,
+    PaymentResponse,
+    PaymentStatus,
+    Stat,
+    list_of,
+)
+
+T = TypeVar("T")
+
+
+class WeBirrClient:
+    """Client for WeBirr merchant APIs."""
+
+    TEST_BASE_URL = "https://api.webirr.net"
+    PROD_BASE_URL = "https://api.webirr.net:8080"
+
+    def __init__(
+        self,
+        merchant_id: str,
+        api_key: str,
+        is_test_env: bool = True,
+        session: requests.Session | None = None,
+        base_url: str | None = None,
+    ) -> None:
+        self.merchant_id = merchant_id or ""
+        self.api_key = api_key or ""
+        self.base_url = (base_url or (self.TEST_BASE_URL if is_test_env else self.PROD_BASE_URL)).rstrip("/")
+        self.session = session or requests.Session()
+        self.session.headers.setdefault("Accept", "application/json")
+
+    def create_bill(self, bill: Bill) -> ApiResponse[str]:
+        """Create a new bill and return the payment code in ``response.res``."""
+
+        self._prepare_bill(bill)
+        return self._send("POST", "einvoice/api/bill", json_body=bill.to_dict())
+
+    def update_bill(self, bill: Bill) -> ApiResponse[str]:
+        """Update an existing unpaid bill."""
+
+        self._prepare_bill(bill)
+        return self._send("PUT", "einvoice/api/bill", json_body=bill.to_dict())
+
+    def delete_bill(self, payment_code: str) -> ApiResponse[str]:
+        """Delete an existing unpaid bill by payment code."""
+
+        return self._send("DELETE", "einvoice/api/bill", params={"wbc_code": payment_code}, json_body={})
+
+    def get_payment_status(self, payment_code: str) -> ApiResponse[PaymentStatus]:
+        """Get single payment status by payment code."""
+
+        return self._send(
+            "GET",
+            "einvoice/api/paymentStatus",
+            params={"wbc_code": payment_code},
+            res_factory=PaymentStatus.from_dict,
+        )
+
+    def get_bill_by_reference(self, bill_reference: str) -> ApiResponse[BillResponse]:
+        """Get a bill by merchant bill reference."""
+
+        return self._send(
+            "GET",
+            "einvoice/api/bill",
+            params={"bill_reference": bill_reference},
+            res_factory=BillResponse.from_dict,
+        )
+
+    def get_bill_by_payment_code(self, payment_code: str) -> ApiResponse[BillResponse]:
+        """Get a bill by WeBirr payment code / WBC code."""
+
+        return self._send(
+            "GET",
+            "einvoice/api/bill",
+            params={"wbc_code": payment_code},
+            res_factory=BillResponse.from_dict,
+        )
+
+    def get_bills(
+        self,
+        payment_status: int = -1,
+        last_time_stamp: str = "",
+        limit: int = 100,
+    ) -> ApiResponse[list[BillResponse]]:
+        """List bills updated after a timestamp cursor."""
+
+        return self._send(
+            "GET",
+            "einvoice/api/bills",
+            params={
+                "payment_status": payment_status,
+                "last_timestamp": last_time_stamp,
+                "limit": limit,
+            },
+            res_factory=list_of(BillResponse.from_dict),
+        )
+
+    def get_payments(
+        self,
+        last_time_stamp: str = "",
+        limit: int = 100,
+    ) -> ApiResponse[list[PaymentResponse]]:
+        """Poll payment updates after a timestamp cursor."""
+
+        return self._send(
+            "GET",
+            "einvoice/api/payments",
+            params={"last_timestamp": last_time_stamp, "limit": limit},
+            res_factory=list_of(PaymentResponse.from_dict),
+        )
+
+    def get_stat(self, date_from: str, date_to: str) -> ApiResponse[Stat]:
+        """Get basic merchant statistics for a date range."""
+
+        return self._send(
+            "GET",
+            "merchant/stat",
+            params={"date_from": date_from, "date_to": date_to},
+            res_factory=Stat.from_dict,
+        )
+
+    def _prepare_bill(self, bill: Bill) -> Bill:
+        if self.merchant_id:
+            bill.merchant_id = self.merchant_id
+        return bill
+
+    def _query(self, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        query: dict[str, Any] = {"api_key": self.api_key}
+        if self.merchant_id:
+            query["merchant_id"] = self.merchant_id
+        if params:
+            query.update(params)
+        return query
+
+    def _send(
+        self,
+        method: str,
+        path: str,
+        params: dict[str, Any] | None = None,
+        json_body: Any | None = None,
+        res_factory: Callable[[Any], T] | None = None,
+    ) -> ApiResponse[T]:
+        url = urljoin(f"{self.base_url}/", path)
+        response = self.session.request(
+            method,
+            url,
+            params=self._query(params),
+            json=json_body,
+            timeout=30,
+        )
+        return self._decode_response(response, res_factory)
+
+    def _decode_response(
+        self,
+        response: requests.Response,
+        res_factory: Callable[[Any], T] | None = None,
+    ) -> ApiResponse[T]:
+        if not 200 <= response.status_code < 300:
+            reason = getattr(response, "reason", "") or ""
+            return ApiResponse(error=f"http error {response.status_code} {reason}".strip())
+
+        try:
+            payload = response.json()
+        except (ValueError, json.JSONDecodeError):
+            return ApiResponse(error="invalid json response")
+
+        if not isinstance(payload, dict):
+            return ApiResponse(error="invalid response shape")
+
+        return ApiResponse.from_dict(payload, res_factory)

webirr/models.py

@@ -0,0 +1,293 @@
+"""Models used by the WeBirr Python SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Generic, Iterable, TypeVar
+
+T = TypeVar("T")
+
+
+def _lookup(data: dict[str, Any], *keys: str, default: Any = "") -> Any:
+    for key in keys:
+        if key in data and data[key] is not None:
+            return data[key]
+    return default
+
+
+def _to_dict(data: Any) -> dict[str, Any]:
+    if data is None:
+        return {}
+    if isinstance(data, dict):
+        return data
+    return vars(data)
+
+
+@dataclass
+class ApiResponse(Generic[T]):
+    """Common WeBirr API response wrapper."""
+
+    error: str | None = None
+    res: T | None = None
+    error_code: str | None = None
+
+    @property
+    def errorCode(self) -> str | None:
+        """Gateway-style alias for callers that prefer the wire name."""
+
+        return self.error_code
+
+    @classmethod
+    def from_dict(
+        cls,
+        data: dict[str, Any],
+        res_factory: Callable[[Any], T] | None = None,
+    ) -> "ApiResponse[T]":
+        raw_res = data.get("res")
+        res = res_factory(raw_res) if res_factory and raw_res is not None else raw_res
+        return cls(
+            error=data.get("error"),
+            res=res,
+            error_code=data.get("errorCode") or data.get("error_code"),
+        )
+
+
+@dataclass
+class Bill:
+    """Create/update request model for WeBirr bills."""
+
+    amount: str = ""
+    customer_code: str = ""
+    customer_name: str = ""
+    customer_phone: str = ""
+    time: str = ""
+    description: str = ""
+    bill_reference: str = ""
+    merchant_id: str = ""
+    extras: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "amount": self.amount,
+            "customerCode": self.customer_code,
+            "customerName": self.customer_name,
+            "customerPhone": self.customer_phone,
+            "time": self.time,
+            "description": self.description,
+            "billReference": self.bill_reference,
+            "merchantID": self.merchant_id,
+            "extras": self.extras or {},
+        }
+
+    @classmethod
+    def from_dict(cls, data: Any) -> "Bill":
+        source = _to_dict(data)
+        return cls(
+            amount=str(_lookup(source, "amount")),
+            customer_code=str(_lookup(source, "customerCode", "customer_code")),
+            customer_name=str(_lookup(source, "customerName", "customer_name")),
+            customer_phone=str(_lookup(source, "customerPhone", "customer_phone")),
+            time=str(_lookup(source, "time")),
+            description=str(_lookup(source, "description")),
+            bill_reference=str(_lookup(source, "billReference", "bill_reference")),
+            merchant_id=str(_lookup(source, "merchantID", "merchant_id")),
+            extras=dict(_lookup(source, "extras", default={}) or {}),
+        )
+
+
+@dataclass
+class BillResponse(Bill):
+    """Bill retrieval/list response model."""
+
+    wbc_code: str = ""
+    payment_status: int | None = None
+    update_time_stamp: str = ""
+
+    @classmethod
+    def from_dict(cls, data: Any) -> "BillResponse":
+        source = _to_dict(data)
+        bill = Bill.from_dict(source)
+        return cls(
+            **bill.__dict__,
+            wbc_code=str(_lookup(source, "wbcCode", "wbc_code")),
+            payment_status=_lookup(source, "paymentStatus", "payment_status", default=None),
+            update_time_stamp=str(_lookup(source, "updateTimeStamp", "update_time_stamp")),
+        )
+
+    @property
+    def wbcCode(self) -> str:
+        return self.wbc_code
+
+    @property
+    def paymentStatus(self) -> int | None:
+        return self.payment_status
+
+    @property
+    def updateTimeStamp(self) -> str:
+        return self.update_time_stamp
+
+
+@dataclass
+class PaymentDetail:
+    """Payment detail returned by single payment status."""
+
+    status: int | None = None
+    id: int | str | None = None
+    bank_id: str = ""
+    payment_reference: str = ""
+    payment_date: str = ""
+    time: str = ""
+    confirmed: bool | None = None
+    confirmed_time: str = ""
+    amount: str = ""
+    wbc_code: str = ""
+    update_time_stamp: str = ""
+
+    @classmethod
+    def from_dict(cls, data: Any) -> "PaymentDetail":
+        source = _to_dict(data)
+        payment_date = str(_lookup(source, "paymentDate", "payment_date", "time"))
+        time = str(_lookup(source, "time", "paymentDate", "payment_date"))
+        return cls(
+            status=_lookup(source, "status", default=None),
+            id=_lookup(source, "id", default=None),
+            bank_id=str(_lookup(source, "bankID", "bank_id")),
+            payment_reference=str(_lookup(source, "paymentReference", "payment_reference")),
+            payment_date=payment_date,
+            time=time,
+            confirmed=_lookup(source, "confirmed", default=None),
+            confirmed_time=str(_lookup(source, "confirmedTime", "confirmed_time")),
+            amount=str(_lookup(source, "amount")),
+            wbc_code=str(_lookup(source, "wbcCode", "wbc_code")),
+            update_time_stamp=str(_lookup(source, "updateTimeStamp", "update_time_stamp")),
+        )
+
+    @property
+    def bankID(self) -> str:
+        return self.bank_id
+
+    @property
+    def paymentReference(self) -> str:
+        return self.payment_reference
+
+    @property
+    def paymentDate(self) -> str:
+        return self.payment_date
+
+    @property
+    def confirmedTime(self) -> str:
+        return self.confirmed_time
+
+    @property
+    def wbcCode(self) -> str:
+        return self.wbc_code
+
+    @property
+    def updateTimeStamp(self) -> str:
+        return self.update_time_stamp
+
+
+@dataclass
+class PaymentStatus:
+    """Single payment status wrapper."""
+
+    status: int | None = None
+    data: PaymentDetail | None = None
+
+    @property
+    def is_paid(self) -> bool:
+        return self.status == 2
+
+    @classmethod
+    def from_dict(cls, data: Any) -> "PaymentStatus":
+        source = _to_dict(data)
+        raw_data = source.get("data")
+        return cls(
+            status=_lookup(source, "status", default=None),
+            data=PaymentDetail.from_dict(raw_data) if raw_data else None,
+        )
+
+
+@dataclass
+class PaymentResponse(PaymentDetail):
+    """Payment item returned by bulk polling and webhook payloads."""
+
+    canceled: bool | None = None
+    canceled_time: str = ""
+
+    @property
+    def is_paid(self) -> bool:
+        return self.status == 2
+
+    @property
+    def is_reversed(self) -> bool:
+        return self.status == 3
+
+    @classmethod
+    def from_dict(cls, data: Any) -> "PaymentResponse":
+        source = _to_dict(data)
+        detail = PaymentDetail.from_dict(source)
+        return cls(
+            **detail.__dict__,
+            canceled=_lookup(source, "canceled", default=None),
+            canceled_time=str(_lookup(source, "canceledTime", "canceled_time")),
+        )
+
+    @property
+    def canceledTime(self) -> str:
+        return self.canceled_time
+
+
+@dataclass
+class Stat:
+    """Basic statistics for bills and payments."""
+
+    n_bills: int | None = None
+    n_bills_paid: int | None = None
+    n_bills_unpaid: int | None = None
+    amount_bills: str = ""
+    amount_paid: str = ""
+    amount_unpaid: str = ""
+
+    @classmethod
+    def from_dict(cls, data: Any) -> "Stat":
+        source = _to_dict(data)
+        return cls(
+            n_bills=_lookup(source, "NBills", "nBills", "n_bills", default=None),
+            n_bills_paid=_lookup(source, "NBillsPaid", "nBillsPaid", "n_bills_paid", default=None),
+            n_bills_unpaid=_lookup(source, "NBillsUnpaid", "nBillsUnpaid", "n_bills_unpaid", default=None),
+            amount_bills=str(_lookup(source, "AmountBills", "amountBills", "amount_bills")),
+            amount_paid=str(_lookup(source, "AmountPaid", "amountPaid", "amount_paid")),
+            amount_unpaid=str(_lookup(source, "AmountUnpaid", "amountUnpaid", "amount_unpaid")),
+        )
+
+    @property
+    def nBills(self) -> int | None:
+        return self.n_bills
+
+    @property
+    def nBillsPaid(self) -> int | None:
+        return self.n_bills_paid
+
+    @property
+    def nBillsUnpaid(self) -> int | None:
+        return self.n_bills_unpaid
+
+    @property
+    def amountBills(self) -> str:
+        return self.amount_bills
+
+    @property
+    def amountPaid(self) -> str:
+        return self.amount_paid
+
+    @property
+    def amountUnpaid(self) -> str:
+        return self.amount_unpaid
+
+
+def list_of(factory: Callable[[Any], T]) -> Callable[[Iterable[Any]], list[T]]:
+    def parse(items: Iterable[Any]) -> list[T]:
+        return [factory(item) for item in items or []]
+
+    return parse

webirr/py.typed

@@ -0,0 +1 @@
+

webirr-1.0.0.dist-info/METADATA

@@ -0,0 +1,493 @@
+Metadata-Version: 2.4
+Name: webirr
+Version: 1.0.0
+Summary: Official Python Client Library for WeBirr Payment Gateway APIs
+Author: WeBirr
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/webirr/webirr-api-python-client
+Project-URL: Source, https://github.com/webirr/webirr-api-python-client
+Project-URL: Issues, https://github.com/webirr/webirr-api-python-client/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28
+Dynamic: license-file
+
+Official Python Client Library for WeBirr Payment Gateway APIs
+
+This Client Library provides convenient access to WeBirr Payment Gateway APIs from Python Applications.
+
+## Install
+
+```bash
+$ pip install webirr
+```
+
+For local development from this repository:
+
+```bash
+$ pip install -e .
+```
+
+## Usage
+
+The library needs to be configured with a *merchant Id* & *API key*. You can get it by contacting [webirr.com](https://webirr.net)
+
+> You can use this library for production or test environments. you will need to set is_test_env=True for test, and False for production apps when creating objects of class WeBirrClient
+
+Examples assume the WeBirr TestEnv and read credentials from environment variables:
+
+```bash
+export WEBIRR_TEST_ENV_MERCHANT_ID="YOUR_TEST_MERCHANT_ID"
+export WEBIRR_TEST_ENV_API_KEY="YOUR_TEST_API_KEY"
+```
+
+Create the client with merchant ID, API key, and environment once. The client automatically sets `Bill.merchant_id` before sending bill create/update requests, so application code and examples should not set `merchant_id` on the bill object.
+
+## Example
+
+The examples below keep the PHP and .NET README flow: create the client, call the API, check `error`, handle the success branch, and print `error_code` on failure.
+
+### Creating a new Bill / Updating an existing Bill on WeBirr Servers
+
+```python
+import os
+from datetime import datetime
+
+from webirr import Bill, WeBirrClient
+
+
+def main():
+    api_key = os.getenv("WEBIRR_TEST_ENV_API_KEY", "")
+    merchant_id = os.getenv("WEBIRR_TEST_ENV_MERCHANT_ID", "")
+
+    # api_key = "YOUR_API_KEY"
+    # merchant_id = "YOUR_MERCHANT_ID"
+
+    api = WeBirrClient(merchant_id, api_key, True)
+
+    bill = Bill()
+    bill.amount = "270.90"
+    bill.customer_code = "cc01"  # it can be email address or phone number if you dont have customer code
+    bill.customer_name = "Elias Haileselassie"
+    bill.customer_phone = "0911000000"  # optional; used for SMS notification when enabled for the merchant
+    bill.time = "2021-07-22 22:14"  # your bill time, always in this format
+    bill.description = "hotel booking"
+    bill.bill_reference = "python/example/" + datetime.now().strftime("%Y%m%d%H%M%S")  # your unique reference number
+
+    print("\nCreating Bill...")
+    res = api.create_bill(bill)
+
+    if not res.error:
+        # success
+        payment_code = res.res  # returns paymentcode such as 429 723 975
+        print(f"\nPayment Code = {payment_code}")  # we may want to save payment code in local db.
+    else:
+        # fail
+        print(f"\nerror: {res.error}")
+        print(f"\nerrorCode: {res.error_code}")  # can be used to handle specific business error such as ERROR_INVALID_INPUT_DUP_REF
+
+    # Update existing bill if it is not paid
+    bill.amount = "278.00"
+    bill.customer_name = "Elias python"
+    # bill.bill_reference = "WE CAN NOT CHANGE THIS"
+
+    print("\nUpdating Bill...")
+    res = api.update_bill(bill)
+
+    if not res.error:
+        # success
+        print("\nbill is updated succesfully")  # res.res will be 'OK'  no need to check here!
+    else:
+        # fail
+        print(f"\nerror: {res.error}")
+        print(f"\nerrorCode: {res.error_code}")  # can be used to handle specific business error such as ERROR_INVALID_INPUT
+
+
+main()
+```
+
+### Getting a Bill and Listing Bills
+
+```python
+import os
+
+from webirr import WeBirrClient
+
+
+def main():
+    api_key = os.getenv("WEBIRR_TEST_ENV_API_KEY", "")
+    merchant_id = os.getenv("WEBIRR_TEST_ENV_MERCHANT_ID", "")
+
+    api = WeBirrClient(merchant_id, api_key, True)
+
+    bill_reference = "YOUR_BILL_REFERENCE"  # BILL_REFERENCE_YOU_SAVED_AFTER_CREATING_A_NEW_BILL
+    payment_code = "YOUR_PAYMENT_CODE"  # PAYMENT_CODE_YOU_SAVED_AFTER_CREATING_A_NEW_BILL
+
+    print("\nGetting bill by reference...")
+    res = api.get_bill_by_reference(bill_reference)
+    if not res.error:
+        # success
+        print("\nBill found by reference.")
+        print(f"\nBill Reference: {res.res.bill_reference}")
+        print(f"\nPayment Code: {res.res.wbc_code}")
+        print(f"\nAmount: {res.res.amount}")
+        print(f"\nPayment Status: {res.res.payment_status}")
+        print(f"\nUpdate Timestamp: {res.res.update_time_stamp}")
+    else:
+        # fail
+        print(f"\nError: {res.error}")
+        print(f"\nError Code: {res.error_code}")
+
+    print("\nGetting bill by payment code...")
+    res = api.get_bill_by_payment_code(payment_code)
+    if not res.error:
+        # success
+        print("\nBill found by payment code.")
+        print(f"\nBill Reference: {res.res.bill_reference}")
+        print(f"\nPayment Code: {res.res.wbc_code}")
+    else:
+        # fail
+        print(f"\nError: {res.error}")
+        print(f"\nError Code: {res.error_code}")
+
+    print("\nListing bills...")
+    payment_status = -1  # -1 all, 0 pending, 1 unconfirmed payment, 2 paid.
+    last_time_stamp = "20251231"  # Date-only cursor; use "20251231235959" when you need time precision.
+    limit = 10
+
+    res = api.get_bills(payment_status, last_time_stamp, limit)
+    if not res.error:
+        # success
+        print(f"\nBills returned: {len(res.res)}")
+        for bill in res.res:
+            print("\n-----------------------------")
+            print(f"\nBill Reference: {bill.bill_reference}")
+            print(f"\nPayment Code: {bill.wbc_code}")
+            print(f"\nAmount: {bill.amount}")
+            print(f"\nPayment Status: {bill.payment_status}")
+            print(f"\nUpdate Timestamp: {bill.update_time_stamp}")
+    else:
+        # fail
+        print(f"\nError: {res.error}")
+        print(f"\nError Code: {res.error_code}")
+
+
+main()
+```
+
+Timestamp cursors can be date-only (`yyyyMMdd`) or include time (`yyyyMMddHHmmss`). Use empty string only when you intentionally want all history from the beginning.
+
+### Getting Payment status of an existing Bill from WeBirr Servers
+
+```python
+import os
+
+from webirr import WeBirrClient
+
+
+def main():
+    api_key = os.getenv("WEBIRR_TEST_ENV_API_KEY", "")
+    merchant_id = os.getenv("WEBIRR_TEST_ENV_MERCHANT_ID", "")
+
+    # api_key = "YOUR_API_KEY"
+    # merchant_id = "YOUR_MERCHANT_ID"
+
+    api = WeBirrClient(merchant_id, api_key, True)
+    payment_code = "PAYMENT_CODE_YOU_SAVED_AFTER_CREATING_A_NEW_BILL"
+
+    print("\nGetting Payment Status...")
+    res = api.get_payment_status(payment_code)
+
+    if not res.error:
+        # success
+        if res.res and res.res.is_paid:
+            payment = res.res.data
+            print("\nbill is paid")
+            print("\nbill payment detail")
+            print(f"\nBank: {payment.bank_id}")
+            print(f"\nBank Reference Number: {payment.payment_reference}")
+            print(f"\nAmount Paid: {payment.amount}")
+            print(f"\nPayment Date: {payment.payment_date}")
+        else:
+            print("\nbill is pending payment")
+    else:
+        # fail
+        print(f"\nerror: {res.error}")
+        print(f"\nerrorCode: {res.error_code}")  # can be used to handle specific business error such as ERROR_INVALID_INPUT
+
+
+main()
+```
+
+*Sample object returned from getPaymentStatus()*
+
+```python
+sample = {
+    "error": None,
+    "res": {
+        "status": 2,
+        "data": {
+            "status": 2,
+            "id": 111219507,
+            "bankID": "cbe_mobile",
+            "paymentReference": "TX70e78862148f4c249606",
+            "paymentDate": "2025-02-26 22:17:19",
+            "confirmed": True,
+            "confirmedTime": "2025-02-26 22:17:19",
+            "amount": "278",
+            "wbcCode": "149 233 514",
+            "updateTimeStamp": "2025022622171981338",
+        },
+    },
+    "errorCode": None,
+}
+```
+
+Use `payment_date` as the payment time field. `time` remains available as a deprecated backward-compatible alias.
+
+### Deleting an existing Bill from WeBirr Servers (if it is not paid)
+
+```python
+import os
+
+from webirr import WeBirrClient
+
+
+def main():
+    api_key = os.getenv("WEBIRR_TEST_ENV_API_KEY", "")
+    merchant_id = os.getenv("WEBIRR_TEST_ENV_MERCHANT_ID", "")
+
+    # api_key = "YOUR_API_KEY"
+    # merchant_id = "YOUR_MERCHANT_ID"
+
+    api = WeBirrClient(merchant_id, api_key, True)
+    payment_code = "PAYMENT_CODE_YOU_SAVED_AFTER_CREATING_A_NEW_BILL"
+
+    print("\nDeleting Bill...")
+    res = api.delete_bill(payment_code)
+
+    if not res.error:
+        # success
+        print("\nbill is deleted succesfully")  # res.res will be 'OK'  no need to check here!
+    else:
+        # fail
+        print(f"\nerror: {res.error}")
+        print(f"\nerrorCode: {res.error_code}")  # can be used to handle specific business error such as ERROR_INVALID_INPUT
+
+
+main()
+```
+
+### Getting list of Payments and process them with Bulk Polling Consumer
+
+```python
+import os
+import time
+
+from webirr import WeBirrClient
+
+
+class PaymentProcessor:
+    def __init__(self):
+        api_key = os.getenv("WEBIRR_TEST_ENV_API_KEY", "")
+        merchant_id = os.getenv("WEBIRR_TEST_ENV_MERCHANT_ID", "")
+        self.api = WeBirrClient(merchant_id, api_key, True)
+        self.last_time_stamp = "20251231"  # Example cursor. Save the last processed payment updateTimeStamp in your database.
+
+    def run_once(self):
+        print("\nRetrieving Payments...")
+        self.fetch_and_process_payments()
+
+    def run_forever(self):
+        while True:
+            self.run_once()
+            print("\nSleeping for 5 seconds...")
+            time.sleep(5)
+
+    def fetch_and_process_payments(self):
+        limit = 100  # Number of records to retrieve depending on your processing requirement & capacity
+        response = self.api.get_payments(self.last_time_stamp, limit)
+
+        if not response.error:
+            # success
+            if len(response.res) == 0:
+                print("\nNo new payments found.")
+            for payment in response.res:
+                self.process_payment(payment)
+                print("\n-----------------------------")
+
+            if len(response.res) > 0:
+                self.last_time_stamp = response.res[-1].update_time_stamp
+                print(f"\nLast Timestamp: {self.last_time_stamp}")  # save updateTimeStamp to your database for the next get_payments() call
+        else:
+            # fail
+            print(f"\nerror: {response.error}")
+            print(f"\nerrorCode: {response.error_code}")  # can be used to handle specific business error such as ERROR_INVALID_INPUT
+
+    def process_payment(self, payment):
+        # Process Payment should be implemented as idempotent operation for production use cases.
+        # This method and logic can be shared among all payment processing consumers: 1. bulk polling, 2. webhook, 3. single payment polling.
+        print(f"\nPayment Status: {payment.status}")
+        if payment.is_paid:
+            print("\nPayment Status Text: Paid.")
+        if payment.is_reversed:
+            print("\nPayment Status Text: Reversed.")
+        print(f"\nBank: {payment.bank_id}")
+        print(f"\nBank Reference Number: {payment.payment_reference}")
+        print(f"\nAmount Paid: {payment.amount}")
+        print(f"\nPayment Date: {payment.payment_date}")
+        print(f"\nReversal/Cancel Date: {payment.canceled_time}")
+        print(f"\nUpdate Timestamp: {payment.update_time_stamp}")
+
+
+PaymentProcessor().run_once()
+```
+
+Bulk polling should persist `updateTimeStamp` only after processing the batch successfully. Polling processors should be idempotent because duplicate/redundant reads are possible.
+
+### Webhooks - Payment processing using Webhook Callbacks
+
+```python
+import hmac
+import json
+import os
+
+from webirr import PaymentResponse
+
+
+class Webhook:
+    # Webhook handler for processing payment updates from WeBirr.
+    # This endpoint should be hosted on a secure server with HTTPS enabled.
+    def handle_request(self, method, provided_auth_key, raw_payload):
+        # Validate request method is POST
+        if method.upper() != "POST":
+            return self.json_response(405, {"error": "Method Not Allowed. POST required."})
+
+        # Authenticate using authKey query string parameter.
+        if not self.is_authenticated(provided_auth_key):
+            return self.json_response(403, {"error": "Unauthorized access. Invalid authKey."})
+
+        if not raw_payload:
+            return self.json_response(400, {"error": "Empty request body."})
+
+        try:
+            payload = json.loads(raw_payload)
+        except json.JSONDecodeError:
+            return self.json_response(400, {"error": "Invalid JSON format."})
+
+        payment_data = payload.get("data", payload)
+        if not payment_data:
+            return self.json_response(400, {"error": "Invalid payment data."})
+
+        payment = PaymentResponse.from_dict(payment_data)
+        self.process_payment(payment)
+
+        return self.json_response(200, {"success": True, "message": "Payment received and queued for processing"})
+
+    def is_authenticated(self, provided_auth_key):
+        expected_auth_key = os.getenv("WEBIRR_WEBHOOK_AUTH_KEY", "YOUR_WEBHOOK_AUTH_KEY")
+        return bool(expected_auth_key) and hmac.compare_digest(expected_auth_key, provided_auth_key or "")
+
+    def process_payment(self, payment):
+        # Process Payment should be implemented as idempotent operation for production use cases.
+        # This method and logic can be shared among all payment processing consumers: 1. bulk polling, 2. webhook, 3. single payment polling.
+        print(f"\nPayment Status: {payment.status}")
+        if payment.is_paid:
+            print("\nPayment Status Text: Paid.")
+        if payment.is_reversed:
+            print("\nPayment Status Text: Reversed.")
+        print(f"\nBank: {payment.bank_id}")
+        print(f"\nBank Reference Number: {payment.payment_reference}")
+        print(f"\nAmount Paid: {payment.amount}")
+        print(f"\nPayment Date: {payment.payment_date}")
+        print(f"\nReversal/Cancel Date: {payment.canceled_time}")
+        print(f"\nUpdate Timestamp: {payment.update_time_stamp}")
+
+    def json_response(self, status_code, body):
+        return {"status_code": status_code, "content_type": "application/json", "body": json.dumps(body)}
+
+
+# Once hosted, the webhook URL needs to be shared with WeBirr for configuration.
+```
+
+### Gettting basic Statistics about bills created and payments received for a date range
+
+```python
+import os
+
+from webirr import WeBirrClient
+
+
+def main():
+    api_key = os.getenv("WEBIRR_TEST_ENV_API_KEY", "")
+    merchant_id = os.getenv("WEBIRR_TEST_ENV_MERCHANT_ID", "")
+
+    # api_key = "YOUR_API_KEY"
+    # merchant_id = "YOUR_MERCHANT_ID"
+
+    api = WeBirrClient(merchant_id, api_key, True)
+
+    date_from = "2025-01-01"  # YYYY-MM-DD
+    date_to = "2030-01-31"  # YYYY-MM-DD
+
+    print("\nRetrieving Statistics...")
+    print(f"\nDate From: {date_from}")
+    print(f"\nDate To: {date_to}")
+
+    response = api.get_stat(date_from, date_to)
+
+    if not response.error:
+        # success
+        stat = response.res
+        print(f"\nNumber of Bills Created: {stat.n_bills}")
+        print(f"\nNumber of Paid Bills: {stat.n_bills_paid}")
+        print(f"\nNumber of Unpaid Bills: {stat.n_bills_unpaid}")
+        print(f"\nAmount of Bills: {stat.amount_bills}")
+        print(f"\nAmount Paid: {stat.amount_paid}")
+        print(f"\nAmount Unpaid: {stat.amount_unpaid}")
+    else:
+        # fail
+        print(f"\nError: {response.error}")
+        print(f"\nError Code: {response.error_code}")
+
+
+main()
+```
+
+## Examples
+
+The `examples` directory includes separate workflows matching the PHP SDK examples:
+
+```bash
+python examples/example1_create_update_bill.py
+python examples/example2_payment_status_single_poll.py
+python examples/example3_delete_bill.py
+python examples/example4_payment_status_bulk_poll.py
+python examples/example5_stat_report.py
+python examples/example6_payment_status_webhook.py
+python examples/example7_get_bill_and_list_bills.py
+```
+
+## Reusable HTTP Session
+
+For batch or mass bill workloads, pass a configured `requests.Session` so your application can reuse connections, configure adapters, and apply its own retry policy:
+
+```python
+import requests
+
+from webirr import WeBirrClient
+
+session = requests.Session()
+api = WeBirrClient(merchant_id, api_key, True, session=session)
+```
+
+The SDK does not silently retry bill creation. Configure retry behavior in your application so duplicate create/update processing remains under your control.

webirr-1.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+webirr/__init__.py,sha256=fGFaAdCTk092PtmF6j-c5GuP0UtZm-15vGahzcEObGQ,428
+webirr/client.py,sha256=B_U5oo1zp4FCEcX0SOeebmZDEULByramR22MkY5XlIw,5708
+webirr/models.py,sha256=Qw6j1fTtxjES_WYMGWK1Ouyv8vT99J4a5TrdxJDNcNI,8641
+webirr/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+webirr-1.0.0.dist-info/licenses/LICENSE,sha256=YAsTWjq1dNhMcg_G_cdQNDp4Y7ZsfYGWqJmohMZiMt4,1058
+webirr-1.0.0.dist-info/METADATA,sha256=2Yfj9eZ6qGAtbVaceadb0etpLd8ZBDuKK9o7yCjevEw,17208
+webirr-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+webirr-1.0.0.dist-info/top_level.txt,sha256=VKdC2Vutf6dR68mk5x3zSRQZTziIohdGU1sL74BNxOA,7
+webirr-1.0.0.dist-info/RECORD,,

webirr-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

webirr-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) WeBirr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

webirr-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+webirr