zenopay-sdk 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

{zenopay_sdk-0.1.0.dist-info → zenopay_sdk-0.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zenopay-sdk
-Version: 0.1.0
+Version: 0.2.0
 Summary: A modern Python SDK for the ZenoPay payment API
 Project-URL: Homepage, https://github.com/elusionhub/zenopay-python-sdk
 Project-URL: Documentation, https://github.com/elusionhub/zenopay-python-sdk#readme
@@ -52,7 +52,7 @@ Description-Content-Type: text/markdown
 
 # ZenoPay Python SDK
 
-Modern Python SDK for ZenoPay payment API with async/sync support and webhook handling.
+Modern Python SDK for ZenoPay payment API with async/sync support, order management, and disbursements.
 
 ## Installation
 
@@ -65,20 +65,22 @@ pip install zenopay-sdk
 ```python
 from elusion.zenopay import ZenoPay
 from elusion.zenopay.models.order import NewOrder
+from elusion.zenopay.utils import generate_order_id
 
-# Initialize client
-client = ZenoPay(account_id="your_account_id")
+# Initialize client (uses environment variables)
+client = ZenoPay()
 
 # Create order (sync)
 with client:
     order = NewOrder(
+        order_id=generate_order_id(),
         buyer_email="customer@example.com",
         buyer_name="John Doe",
-        buyer_phone="0700000000",
+        buyer_phone="07XXXXXXXX",
         amount=1000
     )
     response = client.orders.sync.create(order)
-    print(f"Order ID: {response.data.order_id}")
+    print(f"Order ID: {response.results.order_id}")
 ```
 
 ## Configuration
@@ -86,88 +88,158 @@ with client:
 ### Environment Variables
 
 ```bash
-export ZENOPAY_ACCOUNT_ID="your_account_id"
-export ZENOPAY_API_KEY="your_api_key"        # Optional
-export ZENOPAY_SECRET_KEY="your_secret_key"  # Optional
+export ZENOPAY_API_KEY="your_api_key"
 ```
 
 ### Code Configuration
 
 ```python
 client = ZenoPay(
-    account_id="your_account_id",
     api_key="your_api_key",
-    secret_key="your_secret_key",
     timeout=30.0
 )
 ```
 
-## API Usage
+## Orders API
 
 ### Synchronous Operations
 
 ```python
+from elusion.zenopay import ZenoPay
+from elusion.zenopay.models.order import NewOrder
+from elusion.zenopay.utils import generate_order_id
+
+client = ZenoPay()
+
 # Create order
-with client:
-    order_data = {
-        "buyer_email": "test@example.com",
-        "buyer_name": "Test User",
-        "buyer_phone": "0700000000",
-        "amount": 5000,
-        "webhook_url": "https://yoursite.com/webhook"
-    }
-    response = client.orders.sync.create(order_data)
-    order_id = response.data.order_id
+def create_order():
+    with client:
+        order = NewOrder(
+            order_id=generate_order_id(),
+            buyer_email="test@example.com",
+            buyer_name="Test User",
+            buyer_phone="07XXXXXXXX",
+            amount=1000,
+        )
+        response = client.orders.sync.create(order)
+        return response.results.order_id
 
 # Check status
-with client:
-    status = client.orders.sync.get_status(order_id)
-    print(f"Payment status: {status.data.payment_status}")
+def check_status(order_id: str):
+    with client:
+        response = client.orders.sync.check_status(order_id)
+        return response.results
 
 # Check if paid
-with client:
-    is_paid = client.orders.sync.check_payment(order_id)
+def check_payment(order_id: str):
+    with client:
+        return client.orders.sync.check_payment(order_id)
+
+# Wait for payment completion
+def wait_for_payment(order_id: str):
+    with client:
+        return client.orders.sync.wait_for_payment(order_id)
+
+# Usage example
+if __name__ == "__main__":
+    order_id = create_order()
+    status = check_status(order_id)
+    is_paid = check_payment(order_id)
+
+    print(f"Order: {order_id}")
+    print(f"Status: {status.data[0].payment_status}")
     print(f"Paid: {is_paid}")
 
-# Wait for payment
-with client:
-    try:
-        completed = client.orders.sync.wait_for_payment(order_id, timeout=300)
-        print("Payment completed!")
-    except TimeoutError:
-        print("Payment timeout")
+    order_content = wait_for_payment(order_id)
+    print(f"Order completed: {order_content}")
 ```
 
 ### Asynchronous Operations
 
 ```python
 import asyncio
+from elusion.zenopay import ZenoPay
+from elusion.zenopay.models.order import NewOrder
+from elusion.zenopay.utils import generate_order_id
+
+client = ZenoPay()
+
+# Create order (async)
+async def create_order_async():
+    async with client:
+        order = NewOrder(
+            order_id=generate_order_id(),
+            buyer_email="test@example.com",
+            buyer_name="Test User",
+            buyer_phone="07XXXXXXXX",
+            amount=1000,
+            webhook_url="https://example.com/webhook",
+            metadata={"key": "value"},
+        )
+        response = await client.orders.create(order)
+        return response.results.order_id
+
+# Check status (async)
+async def check_status_async(order_id: str):
+    async with client:
+        response = await client.orders.check_status(order_id)
+        return response.results.data[0].payment_status
 
-async def create_payment():
+# Check payment (async)
+async def check_payment_async(order_id: str):
     async with client:
-        order_data = {
-            "buyer_email": "test@example.com",
-            "buyer_name": "Test User",
-            "buyer_phone": "0700000000",
-            "amount": 5000
-        }
-
-        # Create order
-        response = await client.orders.create(order_data)
-        order_id = response.data.order_id
-
-        # Check status
-        status = await client.orders.get_status(order_id)
-        print(f"Status: {status.data.payment_status}")
-
-        # Wait for completion
-        try:
-            completed = await client.orders.wait_for_payment(order_id)
-            print("Payment completed!")
-        except TimeoutError:
-            print("Payment timeout")
-
-asyncio.run(create_payment())
+        return await client.orders.check_payment(order_id)
+
+# Usage example
+async def async_example():
+    order_id = await create_order_async()
+    status = await check_status_async(order_id)
+    is_paid = await check_payment_async(order_id)
+
+    print(f"Async Order: {order_id}")
+    print(f"Async Status: {status}")
+    print(f"Async Paid: {is_paid}")
+
+asyncio.run(async_example())
+```
+
+## Disbursements API
+
+### Mobile Money Disbursements
+
+```python
+from elusion.zenopay import ZenoPay
+from elusion.zenopay.models.disbursement import NewDisbursement, UtilityCodes
+from elusion.zenopay.utils import generate_order_id
+
+client = ZenoPay()
+
+def disburse():
+    response = client.disbursements.sync.disburse(
+        disbursement_data=NewDisbursement(
+            amount=5000,
+            pin=0000,  # Your ZenoPay PIN
+            transid=generate_order_id(),
+            utilitycode=UtilityCodes.CASHIN,
+            utilityref="07XXXXXXXX"  # Phone number
+        )
+    )
+    return response.results.zenopay_response.result
+
+# Usage
+if __name__ == "__main__":
+    result = disburse()
+    print(f"Disbursement result: {result}")
+```
+
+### Available Utility Codes
+
+```python
+from elusion.zenopay.models.disbursement import UtilityCodes
+
+# Available disbursement types
+UtilityCodes.CASHIN      # Mobile money cash-in
+# Add other available codes as needed
 ```
 
 ## Webhook Handling
@@ -198,9 +270,10 @@ response = client.webhooks.process_webhook_request(webhook_data)
 
 ```python
 from flask import Flask, request, jsonify
+from elusion.zenopay import ZenoPay
 
 app = Flask(__name__)
-client = ZenoPay(account_id="your_account_id")
+client = ZenoPay()
 
 def handle_completed_payment(event):
     order_id = event.payload.order_id
@@ -223,9 +296,10 @@ if __name__ == '__main__':
 
 ```python
 from fastapi import FastAPI, Request
+from elusion.zenopay import ZenoPay
 
 app = FastAPI()
-client = ZenoPay(account_id="your_account_id")
+client = ZenoPay()
 
 def handle_completed_payment(event):
     order_id = event.payload.order_id
@@ -247,33 +321,38 @@ async def webhook(request: Request):
 from elusion.zenopay.exceptions import (
     ZenoPayError,
     ZenoPayValidationError,
-    ZenoPayNetworkError
+    ZenoPayNetworkError,
+    ZenoPayAuthenticationError
 )
 
 try:
     with client:
-        response = client.orders.sync.create(order_data)
+        response = client.orders.sync.create(order)
 except ZenoPayValidationError as e:
     print(f"Validation error: {e.message}")
     print(f"Details: {e.validation_errors}")
+except ZenoPayAuthenticationError as e:
+    print(f"Authentication error: {e.message}")
 except ZenoPayNetworkError as e:
     print(f"Network error: {e.message}")
 except ZenoPayError as e:
     print(f"General error: {e.message}")
 ```
 
-## Order Models
+## Models
 
-### Creating Orders
+### Order Models
 
 ```python
 from elusion.zenopay.models.order import NewOrder
+from elusion.zenopay.utils import generate_order_id
 
-# Using model
+# Create order with all fields
 order = NewOrder(
+    order_id=generate_order_id(),
     buyer_email="customer@example.com",
     buyer_name="John Doe",
-    buyer_phone="0700000000",
+    buyer_phone="07XXXXXXXX",
     amount=1000,
     webhook_url="https://yoursite.com/webhook",
     metadata={
@@ -282,13 +361,30 @@ order = NewOrder(
     }
 )
 
-# Using dictionary
-order_data = {
-    "buyer_email": "customer@example.com",
-    "buyer_name": "John Doe",
-    "buyer_phone": "0700000000",
-    "amount": 1000
-}
+# Minimal order
+order = NewOrder(
+    order_id=generate_order_id(),
+    buyer_email="customer@example.com",
+    buyer_name="John Doe",
+    buyer_phone="07XXXXXXXX",
+    amount=1000
+)
+```
+
+### Disbursement Models
+
+```python
+from elusion.zenopay.models.disbursement import NewDisbursement, UtilityCodes
+from elusion.zenopay.utils import generate_order_id
+
+# Mobile money disbursement
+disbursement = NewDisbursement(
+    amount=5000,
+    pin=0000,  # Your ZenoPay PIN
+    transid=generate_order_id(),
+    utilitycode=UtilityCodes.CASHIN,
+    utilityref="07XXXXXXXX"  # Phone number
+)
 ```
 
 ### Response Models
@@ -296,14 +392,15 @@ order_data = {
 ```python
 # Order creation response
 response = client.orders.sync.create(order)
-print(f"Order ID: {response.data.order_id}")
-print(f"Status: {response.data.status}")
-print(f"Message: {response.data.message}")
+print(f"Order ID: {response.results.order_id}")
 
 # Status check response
-status = client.orders.sync.get_status(order_id)
-print(f"Payment Status: {status.data.payment_status}")
-print(f"Order ID: {status.data.order_id}")
+status = client.orders.sync.check_status(order_id)
+print(f"Payment Status: {status.results.data[0].payment_status}")
+
+# Disbursement response
+response = client.disbursements.sync.disburse(disbursement_data)
+print(f"Result: {response.results.zenopay_response.result}")
 ```
 
 ## API Reference
@@ -313,10 +410,16 @@ print(f"Order ID: {status.data.order_id}")
 | Method           | Sync                                    | Async                                    | Description                |
 | ---------------- | --------------------------------------- | ---------------------------------------- | -------------------------- |
 | Create Order     | `client.orders.sync.create()`           | `await client.orders.create()`           | Create new payment order   |
-| Get Status       | `client.orders.sync.get_status()`       | `await client.orders.get_status()`       | Check order payment status |
+| Check Status     | `client.orders.sync.check_status()`     | `await client.orders.check_status()`     | Check order payment status |
 | Check Payment    | `client.orders.sync.check_payment()`    | `await client.orders.check_payment()`    | Returns boolean if paid    |
 | Wait for Payment | `client.orders.sync.wait_for_payment()` | `await client.orders.wait_for_payment()` | Poll until completed       |
 
+### Disbursement Operations
+
+| Method   | Sync                                   | Async                                   | Description             |
+| -------- | -------------------------------------- | --------------------------------------- | ----------------------- |
+| Disburse | `client.disbursements.sync.disburse()` | `await client.disbursements.disburse()` | Send money disbursement |
+
 ### Webhook Events
 
 | Event     | Handler Method                           | Description        |
@@ -326,15 +429,6 @@ print(f"Order ID: {status.data.order_id}")
 | PENDING   | `client.webhooks.on_payment_pending()`   | Payment initiated  |
 | CANCELLED | `client.webhooks.on_payment_cancelled()` | Payment cancelled  |
 
-## Testing
-
-```python
-# Create test webhook
-test_event = client.webhooks.create_test_webhook("test-order-123", "COMPLETED")
-response = client.webhooks.handle_webhook(test_event)
-print(f"Test response: {response.status}")
-```
-
 ## Best Practices
 
 ### Context Managers
@@ -373,9 +467,20 @@ Use environment variables for sensitive configuration:
 
 ```python
 # Don't hardcode credentials
-client = ZenoPay(account_id=os.getenv('ZENOPAY_ACCOUNT_ID'))
+client = ZenoPay(api_key=os.getenv('ZENOPAY_API_KEY'))
+```
+
+### Generate Unique Order IDs
+
+Always use the built-in utility to generate unique order IDs:
+
+```python
+from elusion.zenopay.utils import generate_order_id
+
+order_id = generate_order_id()  # Generates UUID-based unique ID
 ```
 
+
 ## Support
 
 - **GitHub**: [zenopay-python-sdk](https://github.com/elusionhub/zenopay-python-sdk)

zenopay_sdk-0.2.0.dist-info/RECORD

@@ -0,0 +1,25 @@
+elusion/__init__.py,sha256=p6Agc374IXnYGeJutUZIcfHb-EO-J7vrvUq-Escm_DQ,103
+elusion/zenopay/__init__.py,sha256=T8VVs5TfH2dWonqG1rCu4lGrBKPn-w_egahhAE8xJn8,887
+elusion/zenopay/client.py,sha256=2dT0waURac37ppY1bZRD1saqaARUJ3WAYrfww82Eahs,4315
+elusion/zenopay/config.py,sha256=HYyH9wOSleMORfsXdlEklkejdYQtASc09N2g1JRtDA8,3731
+elusion/zenopay/exceptions.py,sha256=FiZzqwcMpsXqWcBIBupzbS0qdIAbTaw92EpOvPWi-C0,7236
+elusion/zenopay/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+elusion/zenopay/http/__init__.py,sha256=5ODIX-1O_7dGt9y9ky4-oTx8OKDf8qielusi3TXz1v0,84
+elusion/zenopay/http/client.py,sha256=QE-LnamoHV8QcUTyDcmKQUGw9NoIUYipshYWjWNax2E,14236
+elusion/zenopay/models/__init__.py,sha256=P0KmjucqtOdzPvvbAYlSOt6KeUZbkY7I5QGH6xVsS8I,959
+elusion/zenopay/models/common.py,sha256=q6IEu-31ZPjMj9yn0bK36sc2nlxFdrk3ZMBEb4bwHb0,2637
+elusion/zenopay/models/disbursement.py,sha256=9a1Ow4N0ez-J0qLctIxoCixIKd4aERch0u5l-M3lm9E,2552
+elusion/zenopay/models/order.py,sha256=FkvY8ryrDvYuyOA8UX8cq8gfacA3t7rAMO-VrPNemKM,6458
+elusion/zenopay/models/payment.py,sha256=nOa17Eym9tz8FDdZkEcpZyDvrj_r2MZmWrehanyocsE,11184
+elusion/zenopay/models/webhook.py,sha256=0pSOHCabKWo5gl0MrdFQHJizh7fiNdbmh-y45Yx-tbY,4147
+elusion/zenopay/services/__init__.py,sha256=0Gv-DqHaUyoyBwvNpEdU1IaFWYXjdfrPbdwqzhl1saA,258
+elusion/zenopay/services/base.py,sha256=O9f871S1eJ-eBoTsfQhBLMrNjQq5G0nPD7fxaaTqVFc,6153
+elusion/zenopay/services/disbursements.py,sha256=IXXGd1KNlw4e-kU0CQhbNgFhnyujCI40aRAQ-NC9nF4,1722
+elusion/zenopay/services/orders.py,sha256=tY0fNMZpXOgjih1Wibui6WgUdjf29hdvNUI9BAJNvtk,5013
+elusion/zenopay/services/webhooks.py,sha256=ZLQj6TqXCmFbshZ6ZXUQIHOz7Prcf3qPLWnAxYY2mq0,7328
+elusion/zenopay/utils/__init__.py,sha256=f2k7eKJo83Fof2T6NHOvwlmWE5q_d5TaluK1EHt6KkY,207
+elusion/zenopay/utils/helpers.py,sha256=7n2LGQtdSb95z-hx3ph7u8GyFQjfQ3oeAKp7P-lu_ok,2312
+zenopay_sdk-0.2.0.dist-info/METADATA,sha256=kDKZ2GKqYIZ4zXqAHavGbauy3CpPspXEHxE4NJcXUX4,14099
+zenopay_sdk-0.2.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+zenopay_sdk-0.2.0.dist-info/licenses/LICENSE,sha256=jW5Z5KjqFn7c9kMHh3bL0dqsWjjv5oXQ8Cb3YbHiY1A,1067
+zenopay_sdk-0.2.0.dist-info/RECORD,,

zenopay_sdk-0.1.0.dist-info/RECORD

@@ -1,23 +0,0 @@
-elusion/__init__.py,sha256=p6Agc374IXnYGeJutUZIcfHb-EO-J7vrvUq-Escm_DQ,103
-elusion/zenopay/__init__.py,sha256=XBGmKCdXYE2VKz-SrpRIHr4ZsIDfLlDIWxcuFGNMKPI,887
-elusion/zenopay/client.py,sha256=5aXSvREWSvtheUzyPwspHYmDuEkDsclhYz9QUpXIBY0,6974
-elusion/zenopay/config.py,sha256=v1ITpT1nq7jXKuIW2Q8_L4icJes6shJnYhru1VnBUcU,3763
-elusion/zenopay/exceptions.py,sha256=FiZzqwcMpsXqWcBIBupzbS0qdIAbTaw92EpOvPWi-C0,7236
-elusion/zenopay/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-elusion/zenopay/http/__init__.py,sha256=5ODIX-1O_7dGt9y9ky4-oTx8OKDf8qielusi3TXz1v0,84
-elusion/zenopay/http/client.py,sha256=9gpDUpveuFJ3fX5J3in2lh-hZniz4M7hptnZyFojFHY,10496
-elusion/zenopay/models/__init__.py,sha256=Z6sCC7U2xi7gOrShXY5OdKG3EloeynifY2BtCLzGXa4,802
-elusion/zenopay/models/common.py,sha256=_R14-pi0eynbYbl-9jrhgsnIWMwUV21oHWb0ttJzJzI,2906
-elusion/zenopay/models/order.py,sha256=zkCgfU_U9oTa_nAmmgyQAPXitJ3f8kq0ZnjaONukGWs,9471
-elusion/zenopay/models/payment.py,sha256=nOa17Eym9tz8FDdZkEcpZyDvrj_r2MZmWrehanyocsE,11184
-elusion/zenopay/models/webhook.py,sha256=0pSOHCabKWo5gl0MrdFQHJizh7fiNdbmh-y45Yx-tbY,4147
-elusion/zenopay/services/__init__.py,sha256=F8AmAON2gUPep90KoT36jelsIqTiAxtcYLYiRLKtDSw,175
-elusion/zenopay/services/base.py,sha256=VHAycs_FtF_V9baPZ1oVpcWWAGwVqJdYffd31efTJkQ,5357
-elusion/zenopay/services/orders.py,sha256=CrPFkFT9-9ktSqJ3MWhH_mQX41V_51lalDEJ5vn8_3I,5056
-elusion/zenopay/services/webhooks.py,sha256=ZLQj6TqXCmFbshZ6ZXUQIHOz7Prcf3qPLWnAxYY2mq0,7328
-elusion/zenopay/utils/__init__.py,sha256=I7QQ2yt-uLEpqLwBB-r_7ZO-Ifp99qxsYhLoUtHlwuw,139
-elusion/zenopay/utils/helpers.py,sha256=qsARrYRWuLYnoR67kvMhTEJf8E1mzMptToRgrBGytvg,1004
-zenopay_sdk-0.1.0.dist-info/METADATA,sha256=zcD9357Y4vODX3VtqPxgjeR1FuWbnNR39gDTZ-UHuwY,11043
-zenopay_sdk-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-zenopay_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=jW5Z5KjqFn7c9kMHh3bL0dqsWjjv5oXQ8Cb3YbHiY1A,1067
-zenopay_sdk-0.1.0.dist-info/RECORD,,