smartpaystack 0.1.0__tar.gz

smartpaystack-0.1.0/PKG-INFO

@@ -0,0 +1,253 @@
+Metadata-Version: 2.4
+Name: smartpaystack
+Version: 0.1.0
+Summary: A smart, strategy-based, multi-currency Paystack SDK for Python.
+Author-email: Fidelis Chukwunyere <fidelchukwunyere@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/fidel-c/smartpaystack
+Keywords: paystack,payments,fintech,africa,api,wrapper
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.25.1
+
+```markdown
+# SmartPaystack 
+
+A smart, framework-agnostic, strategy-based Paystack integration for Python. 
+
+Stop writing manual math logic to calculate Paystack fees. Just declare your strategy (`ABSORB`, `PASS`, `SPLIT`) and let the package do the rest. Works seamlessly with **FastAPI, Flask, Django, Tornado, or plain Python scripts.**
+
+## ✨ Features
+* **Zero-Math API:** No more Kobo/Cents conversions. Pass native amounts (e.g., `5000` NGN).
+* **Smart Fee Strategies:** Easily absorb fees, pass them to the customer, or split them.
+* **Multi-Currency Routing:** Automatically applies the correct fee caps and percentages for NGN, GHS, ZAR, KES, and USD.
+* **Framework Agnostic Webhooks:** Built-in HMAC SHA512 verifier that works with any web framework.
+* **Fully Typed:** Sweet IDE auto-completion.
+
+---
+
+## 📦 Installation
+
+```bash
+pip install smartpaystack
+
+```
+
+---
+
+##  Quickstart
+
+### 1. Initialization
+
+You can either pass your secret key directly or set it as an environment variable (`PAYSTACK_SECRET_KEY`).
+
+```python
+import os
+from smartpaystack import SmartPaystack
+
+# Option A: Uses the PAYSTACK_SECRET_KEY environment variable
+os.environ["PAYSTACK_SECRET_KEY"] = "sk_live_xxxxxx"
+client = SmartPaystack()
+
+# Option B: Pass it explicitly
+client = SmartPaystack(secret_key="sk_live_xxxxxx")
+
+```
+
+### 2. Collecting Money (Charges)
+
+Stop worrying about fee math. Tell the client how much you want, and who pays the fee.
+
+```python
+from smartpaystack import ChargeStrategy, Currency
+
+# Scenario A: You want exactly ₦50,000. Customer pays the Paystack fee.
+response = client.create_charge(
+    email="customer@email.com", 
+    amount=50000, 
+    currency=Currency.NGN,
+    charge_strategy=ChargeStrategy.PASS 
+)
+print(response["authorization_url"])
+
+# Scenario B: You absorb the fee for a Ghana Cedi transaction.
+response = client.create_charge(
+    email="ghana@email.com",
+    amount=1000,
+    currency=Currency.GHS,
+    charge_strategy=ChargeStrategy.ABSORB
+)
+
+# Scenario C: You split the Paystack fee 50/50 with the customer.
+# If the fee is ₦150, the customer is charged ₦10,075 and you receive ₦9,925.
+response = client.create_charge(
+    email="split@email.com",
+    amount=10000,
+    currency=Currency.NGN,
+    charge_strategy=ChargeStrategy.SPLIT,
+    split_ratio=0.5  # The percentage of the fee the customer pays (0.5 = 50%)
+)
+print(response["authorization_url"])
+
+```
+
+### 3. Sending Money (Transfers)
+
+Sending money is a two-step process: create a recipient, then initiate the transfer.
+
+```python
+# 1. Resolve the account (Optional but recommended)
+account = client.resolve_account_number(account_number="0123456789", bank_code="033")
+print(f"Resolved Name: {account['account_name']}")
+
+# 2. Create the recipient
+recipient = client.create_transfer_recipient(
+    name=account["account_name"],
+    account_number="0123456789",
+    bank_code="033"
+)
+recipient_code = recipient["recipient_code"]
+
+# 3. Send the money (e.g., Send ₦10,500)
+transfer = client.initiate_transfer(
+    amount=10500,
+    recipient_code=recipient_code,
+    reason="Monthly Payout"
+)
+print(f"Transfer Status: {transfer['status']}")
+
+```
+
+---
+
+## 🛡️ Error Handling
+
+When building fintech applications, you must handle failures gracefully. `smartpaystack` provides specific exceptions so you can catch exactly what went wrong.
+
+```python
+from smartpaystack import SmartPaystack
+from smartpaystack.exceptions import PaystackAPIError, PaystackError
+
+client = SmartPaystack()
+
+try:
+    account = client.resolve_account_number("invalid_number", "033")
+except PaystackAPIError as e:
+    # Raised when Paystack returns a 400/500 response, or network fails
+    print(f"Paystack API failed: {str(e)}")
+    # Example Output: Paystack API failed: Could not resolve account name.
+except PaystackError as e:
+    # A generic fallback for any other package-related error
+    print(f"An unexpected error occurred: {str(e)}")
+
+```
+
+**Available Exceptions (from `smartpaystack.exceptions`):**
+
+* `PaystackError`: The base class for all package exceptions.
+* `PaystackAPIError`: Raised when the HTTP request to Paystack fails or returns an error message.
+* `WebhookVerificationError`: Raised when the HMAC signature on an incoming webhook is invalid or missing.
+
+---
+
+## 📡 Verifying Webhooks
+
+Paystack sends webhooks to your server when events happen (like a successful charge or transfer). `smartpaystack` provides a generic `WebhookVerifier` that works with any framework.
+
+### Example: FastAPI
+
+```python
+from fastapi import FastAPI, Request, Header, HTTPException
+from smartpaystack import WebhookVerifier
+from smartpaystack.exceptions import WebhookVerificationError
+
+app = FastAPI()
+verifier = WebhookVerifier(secret_key="sk_live_xxxxxx")
+
+@app.post("/paystack/webhook")
+async def paystack_webhook(request: Request, x_paystack_signature: str = Header(None)):
+    raw_body = await request.body()
+    
+    try:
+        # Verifies the HMAC SHA512 signature and parses the JSON
+        event_data = verifier.verify_and_parse(raw_body, x_paystack_signature)
+    except WebhookVerificationError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+    # Handle the event
+    if event_data["event"] == "charge.success":
+        print("Payment successful!")
+        
+    return {"status": "success"}
+
+```
+
+### Example: Flask
+
+```python
+from flask import Flask, request, jsonify
+from smartpaystack import WebhookVerifier
+from smartpaystack.exceptions import WebhookVerificationError
+
+app = Flask(__name__)
+verifier = WebhookVerifier(secret_key="sk_live_xxxxxx")
+
+@app.route("/paystack/webhook", methods=["POST"])
+def paystack_webhook():
+    signature = request.headers.get("x-paystack-signature")
+    raw_body = request.get_data()
+    
+    try:
+        event_data = verifier.verify_and_parse(raw_body, signature)
+    except WebhookVerificationError as e:
+        return jsonify({"error": str(e)}), 400
+
+    if event_data["event"] == "transfer.success":
+        print("Transfer successful!")
+        
+    return jsonify({"status": "success"}), 200
+
+```
+
+### Example: Django
+
+In your `views.py`, use `@csrf_exempt` since Paystack (an external service) cannot send a CSRF token.
+
+```python
+from django.http import JsonResponse
+from django.views.decorators.csrf import csrf_exempt
+from django.views.decorators.http import require_POST
+from django.conf import settings
+from smartpaystack import WebhookVerifier
+from smartpaystack.exceptions import WebhookVerificationError
+
+# Initialize the verifier (ideally load this from environment or settings)
+verifier = WebhookVerifier(secret_key=getattr(settings, "PAYSTACK_SECRET_KEY", "sk_live_xxxxxx"))
+
+@csrf_exempt
+@require_POST
+def paystack_webhook(request):
+    signature = request.headers.get("x-paystack-signature", "")
+    raw_body = request.body # Django provides the raw bytes here
+    
+    try:
+        event_data = verifier.verify_and_parse(raw_body, signature)
+    except WebhookVerificationError as e:
+        return JsonResponse({"error": str(e)}, status=400)
+
+    # Handle the event
+    if event_data["event"] == "charge.success":
+        print(f"Payment successful for amount: {event_data['data']['amount']}")
+        
+    return JsonResponse({"status": "success"}, status=200)
+
+```
+

smartpaystack-0.1.0/README.md

@@ -0,0 +1,233 @@
+```markdown
+# SmartPaystack 
+
+A smart, framework-agnostic, strategy-based Paystack integration for Python. 
+
+Stop writing manual math logic to calculate Paystack fees. Just declare your strategy (`ABSORB`, `PASS`, `SPLIT`) and let the package do the rest. Works seamlessly with **FastAPI, Flask, Django, Tornado, or plain Python scripts.**
+
+## ✨ Features
+* **Zero-Math API:** No more Kobo/Cents conversions. Pass native amounts (e.g., `5000` NGN).
+* **Smart Fee Strategies:** Easily absorb fees, pass them to the customer, or split them.
+* **Multi-Currency Routing:** Automatically applies the correct fee caps and percentages for NGN, GHS, ZAR, KES, and USD.
+* **Framework Agnostic Webhooks:** Built-in HMAC SHA512 verifier that works with any web framework.
+* **Fully Typed:** Sweet IDE auto-completion.
+
+---
+
+## 📦 Installation
+
+```bash
+pip install smartpaystack
+
+```
+
+---
+
+##  Quickstart
+
+### 1. Initialization
+
+You can either pass your secret key directly or set it as an environment variable (`PAYSTACK_SECRET_KEY`).
+
+```python
+import os
+from smartpaystack import SmartPaystack
+
+# Option A: Uses the PAYSTACK_SECRET_KEY environment variable
+os.environ["PAYSTACK_SECRET_KEY"] = "sk_live_xxxxxx"
+client = SmartPaystack()
+
+# Option B: Pass it explicitly
+client = SmartPaystack(secret_key="sk_live_xxxxxx")
+
+```
+
+### 2. Collecting Money (Charges)
+
+Stop worrying about fee math. Tell the client how much you want, and who pays the fee.
+
+```python
+from smartpaystack import ChargeStrategy, Currency
+
+# Scenario A: You want exactly ₦50,000. Customer pays the Paystack fee.
+response = client.create_charge(
+    email="customer@email.com", 
+    amount=50000, 
+    currency=Currency.NGN,
+    charge_strategy=ChargeStrategy.PASS 
+)
+print(response["authorization_url"])
+
+# Scenario B: You absorb the fee for a Ghana Cedi transaction.
+response = client.create_charge(
+    email="ghana@email.com",
+    amount=1000,
+    currency=Currency.GHS,
+    charge_strategy=ChargeStrategy.ABSORB
+)
+
+# Scenario C: You split the Paystack fee 50/50 with the customer.
+# If the fee is ₦150, the customer is charged ₦10,075 and you receive ₦9,925.
+response = client.create_charge(
+    email="split@email.com",
+    amount=10000,
+    currency=Currency.NGN,
+    charge_strategy=ChargeStrategy.SPLIT,
+    split_ratio=0.5  # The percentage of the fee the customer pays (0.5 = 50%)
+)
+print(response["authorization_url"])
+
+```
+
+### 3. Sending Money (Transfers)
+
+Sending money is a two-step process: create a recipient, then initiate the transfer.
+
+```python
+# 1. Resolve the account (Optional but recommended)
+account = client.resolve_account_number(account_number="0123456789", bank_code="033")
+print(f"Resolved Name: {account['account_name']}")
+
+# 2. Create the recipient
+recipient = client.create_transfer_recipient(
+    name=account["account_name"],
+    account_number="0123456789",
+    bank_code="033"
+)
+recipient_code = recipient["recipient_code"]
+
+# 3. Send the money (e.g., Send ₦10,500)
+transfer = client.initiate_transfer(
+    amount=10500,
+    recipient_code=recipient_code,
+    reason="Monthly Payout"
+)
+print(f"Transfer Status: {transfer['status']}")
+
+```
+
+---
+
+## 🛡️ Error Handling
+
+When building fintech applications, you must handle failures gracefully. `smartpaystack` provides specific exceptions so you can catch exactly what went wrong.
+
+```python
+from smartpaystack import SmartPaystack
+from smartpaystack.exceptions import PaystackAPIError, PaystackError
+
+client = SmartPaystack()
+
+try:
+    account = client.resolve_account_number("invalid_number", "033")
+except PaystackAPIError as e:
+    # Raised when Paystack returns a 400/500 response, or network fails
+    print(f"Paystack API failed: {str(e)}")
+    # Example Output: Paystack API failed: Could not resolve account name.
+except PaystackError as e:
+    # A generic fallback for any other package-related error
+    print(f"An unexpected error occurred: {str(e)}")
+
+```
+
+**Available Exceptions (from `smartpaystack.exceptions`):**
+
+* `PaystackError`: The base class for all package exceptions.
+* `PaystackAPIError`: Raised when the HTTP request to Paystack fails or returns an error message.
+* `WebhookVerificationError`: Raised when the HMAC signature on an incoming webhook is invalid or missing.
+
+---
+
+## 📡 Verifying Webhooks
+
+Paystack sends webhooks to your server when events happen (like a successful charge or transfer). `smartpaystack` provides a generic `WebhookVerifier` that works with any framework.
+
+### Example: FastAPI
+
+```python
+from fastapi import FastAPI, Request, Header, HTTPException
+from smartpaystack import WebhookVerifier
+from smartpaystack.exceptions import WebhookVerificationError
+
+app = FastAPI()
+verifier = WebhookVerifier(secret_key="sk_live_xxxxxx")
+
+@app.post("/paystack/webhook")
+async def paystack_webhook(request: Request, x_paystack_signature: str = Header(None)):
+    raw_body = await request.body()
+    
+    try:
+        # Verifies the HMAC SHA512 signature and parses the JSON
+        event_data = verifier.verify_and_parse(raw_body, x_paystack_signature)
+    except WebhookVerificationError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+    # Handle the event
+    if event_data["event"] == "charge.success":
+        print("Payment successful!")
+        
+    return {"status": "success"}
+
+```
+
+### Example: Flask
+
+```python
+from flask import Flask, request, jsonify
+from smartpaystack import WebhookVerifier
+from smartpaystack.exceptions import WebhookVerificationError
+
+app = Flask(__name__)
+verifier = WebhookVerifier(secret_key="sk_live_xxxxxx")
+
+@app.route("/paystack/webhook", methods=["POST"])
+def paystack_webhook():
+    signature = request.headers.get("x-paystack-signature")
+    raw_body = request.get_data()
+    
+    try:
+        event_data = verifier.verify_and_parse(raw_body, signature)
+    except WebhookVerificationError as e:
+        return jsonify({"error": str(e)}), 400
+
+    if event_data["event"] == "transfer.success":
+        print("Transfer successful!")
+        
+    return jsonify({"status": "success"}), 200
+
+```
+
+### Example: Django
+
+In your `views.py`, use `@csrf_exempt` since Paystack (an external service) cannot send a CSRF token.
+
+```python
+from django.http import JsonResponse
+from django.views.decorators.csrf import csrf_exempt
+from django.views.decorators.http import require_POST
+from django.conf import settings
+from smartpaystack import WebhookVerifier
+from smartpaystack.exceptions import WebhookVerificationError
+
+# Initialize the verifier (ideally load this from environment or settings)
+verifier = WebhookVerifier(secret_key=getattr(settings, "PAYSTACK_SECRET_KEY", "sk_live_xxxxxx"))
+
+@csrf_exempt
+@require_POST
+def paystack_webhook(request):
+    signature = request.headers.get("x-paystack-signature", "")
+    raw_body = request.body # Django provides the raw bytes here
+    
+    try:
+        event_data = verifier.verify_and_parse(raw_body, signature)
+    except WebhookVerificationError as e:
+        return JsonResponse({"error": str(e)}, status=400)
+
+    # Handle the event
+    if event_data["event"] == "charge.success":
+        print(f"Payment successful for amount: {event_data['data']['amount']}")
+        
+    return JsonResponse({"status": "success"}, status=200)
+
+```
+

smartpaystack-0.1.0/calculator.py

@@ -0,0 +1,37 @@
+from decimal import Decimal, ROUND_HALF_UP
+from .enums import Currency
+from .config import CURRENCY_RULES
+
+class PaystackFeeCalculator:
+    """Calculates Paystack transaction fees accurately to avoid floating-point errors."""
+    
+    @classmethod
+    def calculate_fee(cls, amount: Decimal, currency: Currency = Currency.NGN) -> Decimal:
+        rule = CURRENCY_RULES.get(currency, CURRENCY_RULES[Currency.NGN])
+        amount = Decimal(str(amount))
+        
+        fee = amount * rule["percentage"]
+
+        if rule["flat_fee"] > 0 and amount >= rule["threshold"]:
+            fee += rule["flat_fee"]
+
+        if rule["cap"] is not None:
+            fee = min(fee, rule["cap"])
+
+        return fee.quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)
+
+    @classmethod
+    def gross_up_amount(cls, desired_amount: Decimal, currency: Currency = Currency.NGN) -> Decimal:
+        """Calculates the exact amount to charge a customer so the merchant receives the `desired_amount`."""
+        rule = CURRENCY_RULES.get(currency, CURRENCY_RULES[Currency.NGN])
+        desired_amount = Decimal(str(desired_amount))
+        
+        gross = desired_amount / (Decimal("1") - rule["percentage"])
+        
+        if rule["flat_fee"] > 0 and gross >= rule["threshold"]:
+            gross = (desired_amount + rule["flat_fee"]) / (Decimal("1") - rule["percentage"])
+            
+        if rule["cap"] is not None and (gross - desired_amount) > rule["cap"]:
+            gross = desired_amount + rule["cap"]
+            
+        return gross.quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)

smartpaystack-0.1.0/client.py

@@ -0,0 +1,127 @@
+import os
+import uuid
+import requests
+from decimal import Decimal
+from typing import Optional, Dict, Any, Union
+
+from .calculator import PaystackFeeCalculator
+from .enums import ChargeStrategy, Currency, RecipientType, TransferSource
+from .exceptions import PaystackAPIError
+
+class SmartPaystack:
+    """The main client for interacting with the Paystack API."""
+    BASE_URL = "https://api.paystack.co"
+
+    def __init__(self, secret_key: Optional[str] = None) -> None:
+        self.secret_key = secret_key or os.environ.get("PAYSTACK_SECRET_KEY")
+        
+        if not self.secret_key:
+            raise ValueError(
+                "Paystack secret key missing. Pass it to the client "
+                "or set the 'PAYSTACK_SECRET_KEY' environment variable."
+            )
+            
+        self.headers = {
+            "Authorization": f"Bearer {self.secret_key}",
+            "Content-Type": "application/json",
+        }
+
+    def _request(self, method: str, endpoint: str, data: Optional[Dict] = None, params: Optional[Dict] = None) -> Dict[str, Any]:
+        url = f"{self.BASE_URL}{endpoint}"
+        try:
+            response = requests.request(
+                method, url, json=data, params=params, headers=self.headers, timeout=30
+            )
+            result = response.json()
+        except requests.RequestException as e:
+            raise PaystackAPIError(f"Network error: {str(e)}")
+        except ValueError:
+            raise PaystackAPIError("Invalid JSON response from Paystack.")
+
+        if not response.ok or not result.get("status"):
+            raise PaystackAPIError(result.get("message", "API Request Failed"))
+            
+        return result.get("data", result)
+
+    def create_charge(
+        self, 
+        email: str, 
+        amount: Union[int, float, Decimal], 
+        currency: Currency = Currency.NGN,
+        charge_strategy: ChargeStrategy = ChargeStrategy.ABSORB, 
+        split_ratio: float = 0.5, 
+        metadata: Optional[Dict[str, Any]] = None, 
+        **kwargs: Any
+    ) -> Dict[str, Any]:
+        """Initializes a transaction applying the correct fee strategy automatically."""
+        amount = Decimal(str(amount))
+        fee = PaystackFeeCalculator.calculate_fee(amount, currency)
+
+        if charge_strategy == ChargeStrategy.PASS:
+            customer_amount = PaystackFeeCalculator.gross_up_amount(amount, currency)
+        elif charge_strategy == ChargeStrategy.SPLIT:
+            customer_amount = amount + (fee * Decimal(str(split_ratio)))
+        else:
+            customer_amount = amount
+
+        payload = {
+            "email": email,
+            "amount": int(customer_amount * 100), # Convert to lowest denomination (kobo/cents)
+            "currency": currency.value,
+            "reference": kwargs.pop("reference", str(uuid.uuid4())),
+            "metadata": {
+                "smartpaystack_strategy": charge_strategy.value,
+                "merchant_expected": float(amount),
+                "customer_amount": float(customer_amount),
+                **(metadata or {}),
+            },
+            **kwargs
+        }
+        return self._request("POST", "/transaction/initialize", data=payload)
+    
+    def resolve_account_number(self, account_number: str, bank_code: str) -> Dict[str, Any]:
+        """Verifies an account number and bank code before creating a recipient."""
+        params = {"account_number": account_number, "bank_code": bank_code}
+        return self._request("GET", "/bank/resolve", params=params)
+
+    def create_transfer_recipient(
+        self, 
+        name: str, 
+        account_number: str, 
+        bank_code: str, 
+        recipient_type: RecipientType = RecipientType.NUBAN,
+        currency: Currency = Currency.NGN,
+        description: str = "",
+        metadata: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        """Creates a recipient code needed to initiate a transfer."""
+        payload = {
+            "type": recipient_type.value,
+            "name": name,
+            "account_number": account_number,
+            "bank_code": bank_code,
+            "currency": currency.value,
+            "description": description,
+            "metadata": metadata or {}
+        }
+        return self._request("POST", "/transferrecipient", data=payload)
+
+    def initiate_transfer(
+        self, 
+        amount: Union[int, float, Decimal], 
+        recipient_code: str, 
+        currency: Currency = Currency.NGN,
+        source: TransferSource = TransferSource.BALANCE,
+        reason: str = "",
+        reference: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """Initiates a transfer from your Paystack balance to the recipient."""
+        payload = {
+            "source": source.value,
+            "amount": int(Decimal(str(amount)) * 100), # Convert to kobo/cents
+            "currency": currency.value,
+            "recipient": recipient_code,
+            "reason": reason,
+            "reference": reference or str(uuid.uuid4())
+        }
+        return self._request("POST", "/transfer", data=payload)

smartpaystack-0.1.0/config.py

@@ -0,0 +1,30 @@
+from decimal import Decimal
+from .enums import Currency
+
+# Official Paystack fee structures per currency
+CURRENCY_RULES = {
+    Currency.NGN: {
+        "percentage": Decimal("0.015"),
+        "flat_fee": Decimal("100"),
+        "threshold": Decimal("2500"),
+        "cap": Decimal("2000"),
+    },
+    Currency.GHS: {
+        "percentage": Decimal("0.0195"),
+        "flat_fee": Decimal("0"),
+        "threshold": Decimal("0"),
+        "cap": None,
+    },
+    Currency.ZAR: {
+        "percentage": Decimal("0.029"),
+        "flat_fee": Decimal("1"),
+        "threshold": Decimal("0"),
+        "cap": None,
+    },
+    Currency.KES: {
+        "percentage": Decimal("0.029"),
+        "flat_fee": Decimal("0"),
+        "threshold": Decimal("0"),
+        "cap": None,
+    },
+}

smartpaystack-0.1.0/enums.py

@@ -0,0 +1,21 @@
+from enum import Enum
+
+class ChargeStrategy(str, Enum):
+    ABSORB = "absorb"
+    PASS = "pass"
+    SPLIT = "split"
+
+class Currency(str, Enum):
+    NGN = "NGN"
+    GHS = "GHS"
+    ZAR = "ZAR"
+    KES = "KES"
+    USD = "USD"
+
+class RecipientType(str, Enum):
+    NUBAN = "nuban"
+    MOBILE_MONEY = "mobile_money"
+    BASA = "basa"
+
+class TransferSource(str, Enum):
+    BALANCE = "balance"

smartpaystack-0.1.0/exceptions.py

@@ -0,0 +1,11 @@
+class PaystackError(Exception):
+    """Base exception for all SmartPaystack errors."""
+    pass
+
+class PaystackAPIError(PaystackError):
+    """Raised when the Paystack API returns an error or fails."""
+    pass
+
+class WebhookVerificationError(PaystackError):
+    """Raised when a webhook signature fails validation."""
+    pass

smartpaystack-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=65.5.1", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "smartpaystack"
+version = "0.1.0"
+description = "A smart, strategy-based, multi-currency Paystack SDK for Python."
+readme = "README.md"
+authors = [{ name = "Fidelis Chukwunyere", email = "fidelchukwunyere@gmail.com" }]
+license = "MIT"
+keywords = ["paystack", "payments", "fintech", "africa", "api", "wrapper"]
+dependencies = ["requests>=2.25.1"]
+requires-python = ">=3.8"
+classifiers = [
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Operating System :: OS Independent"
+]
+
+[project.urls]
+Homepage = "https://github.com/fidel-c/smartpaystack"
+
+[tool.setuptools]
+py-modules = ["calculator", "client", "config", "enums", "exceptions", "webhooks"]

smartpaystack-0.1.0/setup.cfg

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

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

@@ -0,0 +1,253 @@
+Metadata-Version: 2.4
+Name: smartpaystack
+Version: 0.1.0
+Summary: A smart, strategy-based, multi-currency Paystack SDK for Python.
+Author-email: Fidelis Chukwunyere <fidelchukwunyere@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/fidel-c/smartpaystack
+Keywords: paystack,payments,fintech,africa,api,wrapper
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.25.1
+
+```markdown
+# SmartPaystack 
+
+A smart, framework-agnostic, strategy-based Paystack integration for Python. 
+
+Stop writing manual math logic to calculate Paystack fees. Just declare your strategy (`ABSORB`, `PASS`, `SPLIT`) and let the package do the rest. Works seamlessly with **FastAPI, Flask, Django, Tornado, or plain Python scripts.**
+
+## ✨ Features
+* **Zero-Math API:** No more Kobo/Cents conversions. Pass native amounts (e.g., `5000` NGN).
+* **Smart Fee Strategies:** Easily absorb fees, pass them to the customer, or split them.
+* **Multi-Currency Routing:** Automatically applies the correct fee caps and percentages for NGN, GHS, ZAR, KES, and USD.
+* **Framework Agnostic Webhooks:** Built-in HMAC SHA512 verifier that works with any web framework.
+* **Fully Typed:** Sweet IDE auto-completion.
+
+---
+
+## 📦 Installation
+
+```bash
+pip install smartpaystack
+
+```
+
+---
+
+##  Quickstart
+
+### 1. Initialization
+
+You can either pass your secret key directly or set it as an environment variable (`PAYSTACK_SECRET_KEY`).
+
+```python
+import os
+from smartpaystack import SmartPaystack
+
+# Option A: Uses the PAYSTACK_SECRET_KEY environment variable
+os.environ["PAYSTACK_SECRET_KEY"] = "sk_live_xxxxxx"
+client = SmartPaystack()
+
+# Option B: Pass it explicitly
+client = SmartPaystack(secret_key="sk_live_xxxxxx")
+
+```
+
+### 2. Collecting Money (Charges)
+
+Stop worrying about fee math. Tell the client how much you want, and who pays the fee.
+
+```python
+from smartpaystack import ChargeStrategy, Currency
+
+# Scenario A: You want exactly ₦50,000. Customer pays the Paystack fee.
+response = client.create_charge(
+    email="customer@email.com", 
+    amount=50000, 
+    currency=Currency.NGN,
+    charge_strategy=ChargeStrategy.PASS 
+)
+print(response["authorization_url"])
+
+# Scenario B: You absorb the fee for a Ghana Cedi transaction.
+response = client.create_charge(
+    email="ghana@email.com",
+    amount=1000,
+    currency=Currency.GHS,
+    charge_strategy=ChargeStrategy.ABSORB
+)
+
+# Scenario C: You split the Paystack fee 50/50 with the customer.
+# If the fee is ₦150, the customer is charged ₦10,075 and you receive ₦9,925.
+response = client.create_charge(
+    email="split@email.com",
+    amount=10000,
+    currency=Currency.NGN,
+    charge_strategy=ChargeStrategy.SPLIT,
+    split_ratio=0.5  # The percentage of the fee the customer pays (0.5 = 50%)
+)
+print(response["authorization_url"])
+
+```
+
+### 3. Sending Money (Transfers)
+
+Sending money is a two-step process: create a recipient, then initiate the transfer.
+
+```python
+# 1. Resolve the account (Optional but recommended)
+account = client.resolve_account_number(account_number="0123456789", bank_code="033")
+print(f"Resolved Name: {account['account_name']}")
+
+# 2. Create the recipient
+recipient = client.create_transfer_recipient(
+    name=account["account_name"],
+    account_number="0123456789",
+    bank_code="033"
+)
+recipient_code = recipient["recipient_code"]
+
+# 3. Send the money (e.g., Send ₦10,500)
+transfer = client.initiate_transfer(
+    amount=10500,
+    recipient_code=recipient_code,
+    reason="Monthly Payout"
+)
+print(f"Transfer Status: {transfer['status']}")
+
+```
+
+---
+
+## 🛡️ Error Handling
+
+When building fintech applications, you must handle failures gracefully. `smartpaystack` provides specific exceptions so you can catch exactly what went wrong.
+
+```python
+from smartpaystack import SmartPaystack
+from smartpaystack.exceptions import PaystackAPIError, PaystackError
+
+client = SmartPaystack()
+
+try:
+    account = client.resolve_account_number("invalid_number", "033")
+except PaystackAPIError as e:
+    # Raised when Paystack returns a 400/500 response, or network fails
+    print(f"Paystack API failed: {str(e)}")
+    # Example Output: Paystack API failed: Could not resolve account name.
+except PaystackError as e:
+    # A generic fallback for any other package-related error
+    print(f"An unexpected error occurred: {str(e)}")
+
+```
+
+**Available Exceptions (from `smartpaystack.exceptions`):**
+
+* `PaystackError`: The base class for all package exceptions.
+* `PaystackAPIError`: Raised when the HTTP request to Paystack fails or returns an error message.
+* `WebhookVerificationError`: Raised when the HMAC signature on an incoming webhook is invalid or missing.
+
+---
+
+## 📡 Verifying Webhooks
+
+Paystack sends webhooks to your server when events happen (like a successful charge or transfer). `smartpaystack` provides a generic `WebhookVerifier` that works with any framework.
+
+### Example: FastAPI
+
+```python
+from fastapi import FastAPI, Request, Header, HTTPException
+from smartpaystack import WebhookVerifier
+from smartpaystack.exceptions import WebhookVerificationError
+
+app = FastAPI()
+verifier = WebhookVerifier(secret_key="sk_live_xxxxxx")
+
+@app.post("/paystack/webhook")
+async def paystack_webhook(request: Request, x_paystack_signature: str = Header(None)):
+    raw_body = await request.body()
+    
+    try:
+        # Verifies the HMAC SHA512 signature and parses the JSON
+        event_data = verifier.verify_and_parse(raw_body, x_paystack_signature)
+    except WebhookVerificationError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+    # Handle the event
+    if event_data["event"] == "charge.success":
+        print("Payment successful!")
+        
+    return {"status": "success"}
+
+```
+
+### Example: Flask
+
+```python
+from flask import Flask, request, jsonify
+from smartpaystack import WebhookVerifier
+from smartpaystack.exceptions import WebhookVerificationError
+
+app = Flask(__name__)
+verifier = WebhookVerifier(secret_key="sk_live_xxxxxx")
+
+@app.route("/paystack/webhook", methods=["POST"])
+def paystack_webhook():
+    signature = request.headers.get("x-paystack-signature")
+    raw_body = request.get_data()
+    
+    try:
+        event_data = verifier.verify_and_parse(raw_body, signature)
+    except WebhookVerificationError as e:
+        return jsonify({"error": str(e)}), 400
+
+    if event_data["event"] == "transfer.success":
+        print("Transfer successful!")
+        
+    return jsonify({"status": "success"}), 200
+
+```
+
+### Example: Django
+
+In your `views.py`, use `@csrf_exempt` since Paystack (an external service) cannot send a CSRF token.
+
+```python
+from django.http import JsonResponse
+from django.views.decorators.csrf import csrf_exempt
+from django.views.decorators.http import require_POST
+from django.conf import settings
+from smartpaystack import WebhookVerifier
+from smartpaystack.exceptions import WebhookVerificationError
+
+# Initialize the verifier (ideally load this from environment or settings)
+verifier = WebhookVerifier(secret_key=getattr(settings, "PAYSTACK_SECRET_KEY", "sk_live_xxxxxx"))
+
+@csrf_exempt
+@require_POST
+def paystack_webhook(request):
+    signature = request.headers.get("x-paystack-signature", "")
+    raw_body = request.body # Django provides the raw bytes here
+    
+    try:
+        event_data = verifier.verify_and_parse(raw_body, signature)
+    except WebhookVerificationError as e:
+        return JsonResponse({"error": str(e)}, status=400)
+
+    # Handle the event
+    if event_data["event"] == "charge.success":
+        print(f"Payment successful for amount: {event_data['data']['amount']}")
+        
+    return JsonResponse({"status": "success"}, status=200)
+
+```
+

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

@@ -0,0 +1,13 @@
+README.md
+calculator.py
+client.py
+config.py
+enums.py
+exceptions.py
+pyproject.toml
+webhooks.py
+smartpaystack.egg-info/PKG-INFO
+smartpaystack.egg-info/SOURCES.txt
+smartpaystack.egg-info/dependency_links.txt
+smartpaystack.egg-info/requires.txt
+smartpaystack.egg-info/top_level.txt

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

@@ -0,0 +1 @@
+

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

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

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

@@ -0,0 +1,6 @@
+calculator
+client
+config
+enums
+exceptions
+webhooks

smartpaystack-0.1.0/webhooks.py

@@ -0,0 +1,26 @@
+import hmac
+import hashlib
+import json
+from typing import Dict, Any
+from .exceptions import WebhookVerificationError
+
+class WebhookVerifier:
+    """A framework-agnostic utility for validating Paystack webhook signatures."""
+    
+    def __init__(self, secret_key: str):
+        self.secret_key = secret_key.encode("utf-8")
+
+    def verify_and_parse(self, payload: bytes, signature: str) -> Dict[str, Any]:
+        if not signature:
+            raise WebhookVerificationError("Missing Paystack signature header")
+
+        # Paystack uses HMAC SHA512 to sign webhooks
+        hash_obj = hmac.new(self.secret_key, msg=payload, digestmod=hashlib.sha512)
+        
+        if not hmac.compare_digest(hash_obj.hexdigest(), signature):
+            raise WebhookVerificationError("Invalid Paystack webhook signature")
+
+        try:
+            return json.loads(payload)
+        except json.JSONDecodeError:
+            raise WebhookVerificationError("Invalid JSON payload")