Initial release: qbirr v1.0.0

README.md

@@ -0,0 +1,59 @@
+# qbirr (Python)
+
+Verify Ethiopian bank transfer receipts in real time.
+
+## Install
+
+```bash
+pip install qbirr
+```
+
+## 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="1000017692643",
+)
+
+if r.verified:
+    print(f"✓ Paid by {r.payer}, amount: {r.amount}")
+else:
+    print(f"✗ {r.error}")
+```
+
+## Providers
+
+| provider | Notes |
+|---|---|
+| `cbe` | Needs `receiver_account` |
+| `telebirr` | — |
+| `abyssinia` | Needs `receiver_account` |
+| `dashen` | — |
+| `mpesa` | — |
+| `awash` | `ref` = SMS URL or its token |
+| `ebirr` | `ref` = "tenant/token" or full URL |
+
+## 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