smartpaystack 0.1.0__tar.gz → 0.1.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: smartpaystack
-Version: 0.1.0
+Version: 0.1.2
 Summary: A smart, strategy-based, multi-currency Paystack SDK for Python.
 Author-email: Fidelis Chukwunyere <fidelchukwunyere@gmail.com>
 License-Expression: MIT
@@ -43,7 +43,7 @@ pip install smartpaystack
 
 ---
 
-##  Quickstart
+## 🚀 Quickstart
 
 ### 1. Initialization
 
@@ -99,7 +99,26 @@ print(response["authorization_url"])
 
 ```
 
-### 3. Sending Money (Transfers)
+### 3. Passing Custom Metadata
+
+You can easily attach your own custom data (like order IDs or user IDs) to a charge. The package will safely merge your custom dictionary with its own internal fee calculations so you can access both later in your webhook!
+
+```python
+response = client.create_charge(
+    email="buyer@email.com",
+    amount=15000,
+    charge_strategy=ChargeStrategy.PASS,
+    metadata={
+        "custom_order_id": "ORD-88291",
+        "cart_items": 3
+    }
+)
+
+```
+
+*When this transaction succeeds, your webhook will receive your custom fields alongside `smartpaystack_strategy`, `merchant_expected`, and `customer_amount`.*
+
+### 4. Sending Money (Transfers)
 
 Sending money is a two-step process: create a recipient, then initiate the transfer.
 
@@ -108,11 +127,12 @@ Sending money is a two-step process: create a recipient, then initiate the trans
 account = client.resolve_account_number(account_number="0123456789", bank_code="033")
 print(f"Resolved Name: {account['account_name']}")
 
-# 2. Create the recipient
+# 2. Create the recipient (You can pass metadata here, too!)
 recipient = client.create_transfer_recipient(
     name=account["account_name"],
     account_number="0123456789",
-    bank_code="033"
+    bank_code="033",
+    metadata={"internal_worker_id": "W-990"}
 )
 recipient_code = recipient["recipient_code"]
 
@@ -184,7 +204,12 @@ async def paystack_webhook(request: Request, x_paystack_signature: str = Header(
 
     # Handle the event
     if event_data["event"] == "charge.success":
-        print("Payment successful!")
+        data = event_data["data"]
+        # Retrieve the math breakdown and your custom metadata!
+        merchant_keeps = data["metadata"]["merchant_expected"]
+        order_id = data["metadata"].get("custom_order_id")
+        
+        print(f"Payment successful for Order {order_id}! Expected payout: {merchant_keeps}")
         
     return {"status": "success"}
 
@@ -251,3 +276,5 @@ def paystack_webhook(request):
 
 ```
 
+```
+

{smartpaystack-0.1.0 → smartpaystack-0.1.2}/README.md

@@ -23,7 +23,7 @@ pip install smartpaystack
 
 ---
 
-##  Quickstart
+## 🚀 Quickstart
 
 ### 1. Initialization
 
@@ -79,7 +79,26 @@ print(response["authorization_url"])
 
 ```
 
-### 3. Sending Money (Transfers)
+### 3. Passing Custom Metadata
+
+You can easily attach your own custom data (like order IDs or user IDs) to a charge. The package will safely merge your custom dictionary with its own internal fee calculations so you can access both later in your webhook!
+
+```python
+response = client.create_charge(
+    email="buyer@email.com",
+    amount=15000,
+    charge_strategy=ChargeStrategy.PASS,
+    metadata={
+        "custom_order_id": "ORD-88291",
+        "cart_items": 3
+    }
+)
+
+```
+
+*When this transaction succeeds, your webhook will receive your custom fields alongside `smartpaystack_strategy`, `merchant_expected`, and `customer_amount`.*
+
+### 4. Sending Money (Transfers)
 
 Sending money is a two-step process: create a recipient, then initiate the transfer.
 
@@ -88,11 +107,12 @@ Sending money is a two-step process: create a recipient, then initiate the trans
 account = client.resolve_account_number(account_number="0123456789", bank_code="033")
 print(f"Resolved Name: {account['account_name']}")
 
-# 2. Create the recipient
+# 2. Create the recipient (You can pass metadata here, too!)
 recipient = client.create_transfer_recipient(
     name=account["account_name"],
     account_number="0123456789",
-    bank_code="033"
+    bank_code="033",
+    metadata={"internal_worker_id": "W-990"}
 )
 recipient_code = recipient["recipient_code"]
 
@@ -164,7 +184,12 @@ async def paystack_webhook(request: Request, x_paystack_signature: str = Header(
 
     # Handle the event
     if event_data["event"] == "charge.success":
-        print("Payment successful!")
+        data = event_data["data"]
+        # Retrieve the math breakdown and your custom metadata!
+        merchant_keeps = data["metadata"]["merchant_expected"]
+        order_id = data["metadata"].get("custom_order_id")
+        
+        print(f"Payment successful for Order {order_id}! Expected payout: {merchant_keeps}")
         
     return {"status": "success"}
 
@@ -231,3 +256,5 @@ def paystack_webhook(request):
 
 ```
 
+```
+

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "smartpaystack"
-version = "0.1.0"
+version = "0.1.2"
 description = "A smart, strategy-based, multi-currency Paystack SDK for Python."
 readme = "README.md"
 authors = [{ name = "Fidelis Chukwunyere", email = "fidelchukwunyere@gmail.com" }]

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: smartpaystack
-Version: 0.1.0
+Version: 0.1.2
 Summary: A smart, strategy-based, multi-currency Paystack SDK for Python.
 Author-email: Fidelis Chukwunyere <fidelchukwunyere@gmail.com>
 License-Expression: MIT
@@ -43,7 +43,7 @@ pip install smartpaystack
 
 ---
 
-##  Quickstart
+## 🚀 Quickstart
 
 ### 1. Initialization
 
@@ -99,7 +99,26 @@ print(response["authorization_url"])
 
 ```
 
-### 3. Sending Money (Transfers)
+### 3. Passing Custom Metadata
+
+You can easily attach your own custom data (like order IDs or user IDs) to a charge. The package will safely merge your custom dictionary with its own internal fee calculations so you can access both later in your webhook!
+
+```python
+response = client.create_charge(
+    email="buyer@email.com",
+    amount=15000,
+    charge_strategy=ChargeStrategy.PASS,
+    metadata={
+        "custom_order_id": "ORD-88291",
+        "cart_items": 3
+    }
+)
+
+```
+
+*When this transaction succeeds, your webhook will receive your custom fields alongside `smartpaystack_strategy`, `merchant_expected`, and `customer_amount`.*
+
+### 4. Sending Money (Transfers)
 
 Sending money is a two-step process: create a recipient, then initiate the transfer.
 
@@ -108,11 +127,12 @@ Sending money is a two-step process: create a recipient, then initiate the trans
 account = client.resolve_account_number(account_number="0123456789", bank_code="033")
 print(f"Resolved Name: {account['account_name']}")
 
-# 2. Create the recipient
+# 2. Create the recipient (You can pass metadata here, too!)
 recipient = client.create_transfer_recipient(
     name=account["account_name"],
     account_number="0123456789",
-    bank_code="033"
+    bank_code="033",
+    metadata={"internal_worker_id": "W-990"}
 )
 recipient_code = recipient["recipient_code"]
 
@@ -184,7 +204,12 @@ async def paystack_webhook(request: Request, x_paystack_signature: str = Header(
 
     # Handle the event
     if event_data["event"] == "charge.success":
-        print("Payment successful!")
+        data = event_data["data"]
+        # Retrieve the math breakdown and your custom metadata!
+        merchant_keeps = data["metadata"]["merchant_expected"]
+        order_id = data["metadata"].get("custom_order_id")
+        
+        print(f"Payment successful for Order {order_id}! Expected payout: {merchant_keeps}")
         
     return {"status": "success"}
 
@@ -251,3 +276,5 @@ def paystack_webhook(request):
 
 ```
 
+```
+

{smartpaystack-0.1.0 → smartpaystack-0.1.2}/smartpaystack.egg-info/SOURCES.txt

@@ -1,11 +1,5 @@
 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-0.1.0/calculator.py

@@ -1,37 +0,0 @@
-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

@@ -1,127 +0,0 @@
-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

@@ -1,30 +0,0 @@
-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

@@ -1,21 +0,0 @@
-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

@@ -1,11 +0,0 @@
-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/webhooks.py

@@ -1,26 +0,0 @@
-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")