# qbirr (Python) Verify Ethiopian bank transfer receipts in real time. ## Install ```bash pip install "git+https://git.qbirr.com/admin/sdk-python.git" ``` These packages are not on the public registries yet, so the command above installs straight from the repository. ## Quick start ```python from qbirr import Qbirr qb = Qbirr(api_key="your_key_from_dashboard") r = qb.verify( provider="cbe", ref="FT23001234ABC", amount=500, receiver_name="YOUR FULL NAME", receiver_account="1000123456789", ) if r.verified: print(f"✓ Paid by {r.payer}, amount: {r.amount}") else: print(f"✗ {r.error}") ``` ## Providers | provider | Notes | |---|---| | `cbe` | Needs `receiver_account`. `ref` = full receipt link, `v2-…` token, or just the token | | `telebirr` | — | | `abyssinia` | Needs `receiver_account` | | `dashen` | — | | `mpesa` | — | | `awash` | `ref` = SMS URL or its token | | `ebirr` | `ref` = "tenant/token" or full URL | ## Reference formats `ref` accepts whatever the customer pasted. For **CBE**, all of these are the *same* payment, and qbirr reduces them to a single identity so one receipt cannot be verified twice: | What the customer pasted | Example | |---|---| | The full receipt link | `https://mbreciept.cbe.com.et/v2-hfHCxHoqlCB1LfGG6kJY` | | The token with its `v2-` prefix | `v2-hfHCxHoqlCB1LfGG6kJY` | | Just the token | `hfHCxHoqlCB1LfGG6kJY` | | The legacy `FT…` reference | `FT262693ZS18` | Case is ignored when deciding whether a receipt has already been used. **Awash** takes the SMS URL or its token; **eBirr** takes the URL or `"tenant/token"`. ## Webhooks Subscribe from the dashboard. qbirr POSTs `verification.created` for **both** outcomes, so always read `data.verified` — never treat delivery alone as payment. ``` X-Qbirr-Signature: sha256= # HMAC-SHA256(secret, ".") X-Qbirr-Timestamp: X-Qbirr-Event: verification.created X-Qbirr-Delivery: ``` `data.client_ref` echoes the tag your own upload sent, so an order can be found without inferring it from the provider and amount. It is `null` if you did not send one. Answer `2xx` once you have processed the event. A **4xx is final** — qbirr will not retry a request your endpoint refused. Return **5xx** (or time out) to have it retried with exponential backoff. ## Quota Only **verified** lookups count against your monthly quota. A failed, retryable or duplicate lookup does not consume quota. ## Errors ```python from qbirr import Qbirr, QbirrError try: r = qb.verify(...) except QbirrError as e: print(f"API error {e.status}: {e}") ``` Verification *failures* (wrong amount, wrong receiver) are NOT exceptions — they're returned as `VerifyResult(verified=False, error="...")`. ## License MIT