afconwave 0.1.0__tar.gz

afconwave-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AfconWave
+
+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.

afconwave-0.1.0/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: afconwave
+Version: 0.1.0
+Summary: Official AfconWave Python SDK
+Author: AfconWave Team
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+License-File: LICENSE
+Requires-Dist: requests>=2.25.0
+Dynamic: author
+Dynamic: classifier
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: summary

afconwave-0.1.0/README.md

@@ -0,0 +1,206 @@
+# afconwave — Official Python SDK
+
+> The official Python client library for the AfconWave Payments API.
+
+[![PyPI version](https://img.shields.io/pypi/v/afconwave.svg)](https://pypi.org/project/afconwave/)
+[![Python](https://img.shields.io/badge/Python-3.8+-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## Features
+
+- ✅ Python 3.8+ compatible
+- 🌍 Payments, Payouts, and Refunds in one library
+- 🔒 Secure API key handling
+- 🔔 Webhook signature verification helper
+- 🧪 Sandbox-ready with test keys
+
+---
+
+## Installation
+
+```bash
+pip install afconwave
+```
+
+---
+
+## Quick Start
+
+```python
+from afconwave import AfconWave
+
+afw = AfconWave(secret_key="sk_test_your_key_here")
+```
+
+---
+
+## Usage Guide
+
+### Create a Payment
+
+```python
+payment = afw.create_payment(
+    amount=5000,            # Amount in minor units (5000 = 50 XAF)
+    currency="XAF",
+    description="Order #1234",
+    callback_url="https://yoursite.com/payment/callback",
+    customer={
+        "name": "Jean Dupont",
+        "email": "jean@example.com",
+        "phone": "+237600000000",
+    },
+    metadata={"order_id": "ORD-1234"}
+)
+
+print(payment["checkout_url"])  # Redirect user here
+print(payment["id"])            # e.g., pay_507f191e8180f
+```
+
+### Retrieve a Payment
+
+```python
+payment = afw.retrieve_payment("pay_507f191e8180f")
+
+print(payment["status"])   # "pending" | "success" | "failed"
+print(payment["amount"])
+print(payment["paid_at"])
+```
+
+### Create a Payout
+
+```python
+payout = afw.create_payout(
+    amount=10000,
+    currency="XAF",
+    recipient={
+        "phone": "+237600000001",
+        "network": "MTN",  # "MTN" | "ORANGE" | "MOOV" | "WAVE"
+        "name": "Marie Kamga",
+    },
+    reference="PAYOUT-REF-001"
+)
+
+print(payout["status"])  # "pending" | "success" | "failed"
+```
+
+### List Payments
+
+```python
+result = afw.list_payments(limit=20, status="success")
+
+for payment in result["data"]:
+    print(payment["id"], payment["amount"], payment["status"])
+```
+
+---
+
+## Webhook Verification
+
+Verify that incoming webhooks are genuinely from AfconWave:
+
+```python
+import hashlib
+import hmac
+from flask import Flask, request, abort
+
+app = Flask(__name__)
+WEBHOOK_SECRET = "your_webhook_secret"
+
+@app.route("/webhooks/afconwave", methods=["POST"])
+def handle_webhook():
+    signature = request.headers.get("X-AfconWave-Signature", "")
+    payload = request.get_data(as_text=True)
+
+    expected = hmac.new(
+        WEBHOOK_SECRET.encode(),
+        payload.encode(),
+        hashlib.sha256
+    ).hexdigest()
+
+    if not hmac.compare_digest(expected, signature):
+        abort(400, "Invalid signature")
+
+    event = request.get_json()
+
+    if event["event"] == "payment.success":
+        print("Payment received:", event["data"]["id"])
+    elif event["event"] == "payment.failed":
+        print("Payment failed")
+    elif event["event"] == "payout.success":
+        print("Payout delivered")
+
+    return "OK", 200
+```
+
+---
+
+## Error Handling
+
+```python
+from afconwave import AfconWave, AfconWaveError
+
+afw = AfconWave(secret_key="sk_test_...")
+
+try:
+    payment = afw.create_payment(amount=5000, currency="XAF", callback_url="...")
+except AfconWaveError as e:
+    print(f"API Error {e.status_code}: {e.message}")
+except Exception as e:
+    print(f"Unexpected error: {e}")
+```
+
+---
+
+## Configuration
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `secret_key` | `str` | **required** | Your AfconWave secret API key |
+| `base_url` | `str` | `https://api.afconwave.com/v1` | API base URL |
+| `timeout` | `int` | `30` | Request timeout (seconds) |
+
+---
+
+## Sandbox / Testing
+
+Use test keys prefixed with `sk_test_` for sandbox mode. No real transactions occur.
+
+```python
+afw = AfconWave(secret_key="sk_test_...")
+```
+
+---
+
+## Django / Flask Integration
+
+### Django (example view)
+
+```python
+from django.http import JsonResponse
+from django.views.decorators.csrf import csrf_exempt
+from afconwave import AfconWave
+
+afw = AfconWave(secret_key="sk_live_...")
+
+def create_checkout(request):
+    payment = afw.create_payment(
+        amount=int(request.POST["amount"]),
+        currency="XAF",
+        callback_url="https://yoursite.com/payment/success",
+    )
+    return JsonResponse({"checkout_url": payment["checkout_url"]})
+```
+
+---
+
+## Documentation
+
+Full API documentation: [docs.afconwave.com](https://docs.afconwave.com)
+
+---
+
+## License
+
+MIT © AfconWave

afconwave-0.1.0/afconwave/__init__.py

@@ -0,0 +1,159 @@
+import requests
+import hmac
+import hashlib
+import json
+import time
+
+# ─── Exceptions ────────────────────────────────────────────────────────────────
+
+class AfconWaveError(Exception):
+    def __init__(self, message, status_code=None, code=None):
+        self.message = message
+        self.status_code = status_code
+        self.code = code
+        super().__init__(self.message)
+
+# ─── Resources ────────────────────────────────────────────────────────────────
+
+class Resource:
+    def __init__(self, client):
+        self.client = client
+
+class Payments(Resource):
+    def create(self, **kwargs):
+        return self.client.request('POST', '/payments', data=kwargs)
+        
+    def retrieve(self, payment_id):
+        return self.client.request('GET', f'/payments/{payment_id}')
+    
+    def list(self, **kwargs):
+        return self.client.request('GET', '/payments', params=kwargs)
+
+class Payouts(Resource):
+    def create(self, **kwargs):
+        return self.client.request('POST', '/payouts', data=kwargs)
+        
+    def retrieve(self, payout_id):
+        return self.client.request('GET', f'/payouts/{payout_id}')
+
+class Crypto(Resource):
+    def buy(self, **kwargs):
+        return self.client.request('POST', '/crypto/buy', data=kwargs)
+
+class Refunds(Resource):
+    def create(self, payment_id: str, amount: float, reason: str = None):
+        return self.client.request('POST', '/refunds', data={
+            'paymentId': payment_id,
+            'amount': amount,
+            'reason': reason
+        })
+
+    def list(self):
+        return self.client.request('GET', '/refunds')
+
+class Disputes(Resource):
+    def open(self, transaction_id: str, reason: str, description: str):
+        return self.client.request('POST', '/disputes', data={
+            'transactionId': transaction_id,
+            'reason': reason,
+            'description': description
+        })
+
+    def list(self):
+        return self.client.request('GET', '/disputes')
+
+    def resolve(self, dispute_id: str, resolution: str, resolution_details: str = None):
+        return self.client.request('POST', f'/disputes/{dispute_id}/resolve', data={
+            'resolution': resolution,
+            'resolutionDetails': resolution_details
+        })
+
+# ─── Main Client ───────────────────────────────────────────────────────────────
+
+class AfconWave:
+    def __init__(self, secret_key: str, base_url: str = 'https://api.afconwave.com/api/v1', timeout: int = 30):
+        self.secret_key = secret_key
+        self.base_url = base_url
+        self.timeout = timeout
+        
+        self.payments = Payments(self)
+        self.payouts = Payouts(self)
+        self.crypto = Crypto(self)
+        self.refunds = Refunds(self)
+        self.disputes = Disputes(self)
+
+    @staticmethod
+    def verify_webhook_signature(payload: str, signature: str, secret: str, tolerance: int = 300) -> bool:
+        """
+        Verifies that an incoming webhook was sent by AfconWave and checks for replay attacks.
+        
+        :param payload: The raw request body string.
+        :param signature: The X-Afcon-Signature header.
+        :param secret: Your webhook secret.
+        :param tolerance: Maximum allowed age in seconds (default 300).
+        """
+        # 1. Verify Signature
+        expected = hmac.new(
+            secret.encode(),
+            payload.encode(),
+            hashlib.sha256
+        ).hexdigest()
+        
+        if not hmac.compare_digest(expected, signature):
+            return False
+
+        # 2. Verify Timestamp (Replay Protection)
+        try:
+            data = json.loads(payload)
+            if 'timestamp' in data:
+                current_time = time.time() # seconds
+                webhook_time = data['timestamp'] / 1000.0 # convert ms to seconds
+                age = abs(current_time - webhook_time)
+
+                if age > tolerance:
+                    return False
+        except:
+            pass
+
+        return True
+
+    def request(self, method: str, path: str, data: dict = None, params: dict = None):
+        headers = {
+            'Authorization': f'Bearer {self.secret_key}',
+            'Content-Type': 'application/json',
+            'Accept': 'application/json'
+        }
+        url = f"{self.base_url}{path}"
+        
+        try:
+            response = requests.request(
+                method, url, headers=headers, json=data, params=params, timeout=self.timeout
+            )
+            
+            res_data = response.json()
+            
+            if not response.ok:
+                raise AfconWaveError(
+                    message=res_data.get('error', response.reason),
+                    status_code=response.status_code,
+                    code=res_data.get('code')
+                )
+                
+            return res_data.get('data', res_data)
+            
+        except requests.exceptions.RequestException as e:
+            raise AfconWaveError(message=str(e))
+
+    # ─── Top-level Convenience Methods (Matches README) ─────────────────────
+
+    def create_payment(self, **kwargs):
+        return self.payments.create(**kwargs)
+
+    def retrieve_payment(self, payment_id: str):
+        return self.payments.retrieve(payment_id)
+
+    def list_payments(self, **kwargs):
+        return self.payments.list(**kwargs)
+
+    def create_payout(self, **kwargs):
+        return self.payouts.create(**kwargs)

afconwave-0.1.0/afconwave.egg-info/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: afconwave
+Version: 0.1.0
+Summary: Official AfconWave Python SDK
+Author: AfconWave Team
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+License-File: LICENSE
+Requires-Dist: requests>=2.25.0
+Dynamic: author
+Dynamic: classifier
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: summary

afconwave-0.1.0/afconwave.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+LICENSE
+README.md
+setup.py
+afconwave/__init__.py
+afconwave.egg-info/PKG-INFO
+afconwave.egg-info/SOURCES.txt
+afconwave.egg-info/dependency_links.txt
+afconwave.egg-info/requires.txt
+afconwave.egg-info/top_level.txt

afconwave-0.1.0/afconwave.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

afconwave-0.1.0/afconwave.egg-info/requires.txt

@@ -0,0 +1 @@
+requests>=2.25.0

afconwave-0.1.0/afconwave.egg-info/top_level.txt

@@ -0,0 +1 @@
+afconwave

afconwave-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

afconwave-0.1.0/setup.py

@@ -0,0 +1,17 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="afconwave",
+    version="0.1.0",
+    description="Official AfconWave Python SDK",
+    author="AfconWave Team",
+    packages=find_packages(),
+    install_requires=[
+        "requests>=2.25.0",
+    ],
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+    ],
+)