smartpaystack 0.1.2__tar.gz → 0.1.3__tar.gz

{smartpaystack-0.1.2 → smartpaystack-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: smartpaystack
-Version: 0.1.2
+Version: 0.1.3
 Summary: A smart, strategy-based, multi-currency Paystack SDK for Python.
 Author-email: Fidelis Chukwunyere <fidelchukwunyere@gmail.com>
 License-Expression: MIT

{smartpaystack-0.1.2 → smartpaystack-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "smartpaystack"
-version = "0.1.2"
+version = "0.1.3"
 description = "A smart, strategy-based, multi-currency Paystack SDK for Python."
 readme = "README.md"
 authors = [{ name = "Fidelis Chukwunyere", email = "fidelchukwunyere@gmail.com" }]
@@ -26,5 +26,6 @@ classifiers = [
 [project.urls]
 Homepage = "https://github.com/fidel-c/smartpaystack"
 
-[tool.setuptools]
-py-modules = ["calculator", "client", "config", "enums", "exceptions", "webhooks"]
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["smartpaystack*"]

smartpaystack-0.1.3/smartpaystack/__init__.py

@@ -0,0 +1,18 @@
+from .client import SmartPaystack
+from .webhooks import WebhookVerifier
+from .enums import ChargeStrategy, Currency, RecipientType, TransferSource
+from .exceptions import PaystackError, PaystackAPIError, WebhookVerificationError
+
+__version__ = "0.1.3"
+
+__all__ = [
+    "SmartPaystack",
+    "WebhookVerifier",
+    "ChargeStrategy",
+    "Currency",
+    "RecipientType",
+    "TransferSource",
+    "PaystackError",
+    "PaystackAPIError",
+    "WebhookVerificationError"
+]

smartpaystack-0.1.3/smartpaystack/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.3/smartpaystack/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.3/smartpaystack/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.3/smartpaystack/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.3/smartpaystack/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.3/smartpaystack/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")

{smartpaystack-0.1.2 → smartpaystack-0.1.3}/smartpaystack.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: smartpaystack
-Version: 0.1.2
+Version: 0.1.3
 Summary: A smart, strategy-based, multi-currency Paystack SDK for Python.
 Author-email: Fidelis Chukwunyere <fidelchukwunyere@gmail.com>
 License-Expression: MIT

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

@@ -0,0 +1,14 @@
+README.md
+pyproject.toml
+smartpaystack/__init__.py
+smartpaystack/calculator.py
+smartpaystack/client.py
+smartpaystack/config.py
+smartpaystack/enums.py
+smartpaystack/exceptions.py
+smartpaystack/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.3/smartpaystack.egg-info/top_level.txt

@@ -0,0 +1 @@
+smartpaystack

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

@@ -1,7 +0,0 @@
-README.md
-pyproject.toml
-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.2/smartpaystack.egg-info/top_level.txt

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