snippe 0.1.0__py3-none-any.whl

snippe/__init__.py

@@ -0,0 +1,67 @@
+"""
+Snippe - Python SDK for Snippe Payment API.
+
+Accept payments via mobile money, card, and QR code.
+
+Usage:
+    >>> from snippe import Snippe, Customer
+    >>> client = Snippe("your_api_key")
+    >>> payment = client.create_mobile_payment(
+    ...     amount=1000,
+    ...     currency="TZS",
+    ...     phone_number="0788500000",
+    ...     customer=Customer(firstname="John", lastname="Doe")
+    ... )
+    >>> print(payment.reference)
+"""
+
+from .client import AsyncSnippe, Snippe
+from .exceptions import (
+    AuthenticationError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    SnippeError,
+    ValidationError,
+    WebhookVerificationError,
+)
+from .models import (
+    Balance,
+    Customer,
+    Payment,
+    PaymentDetails,
+    PaymentList,
+    WebhookPayload,
+)
+from .types import Currency, PaymentStatus, PaymentType, WebhookEvent
+from .webhooks import WebhookHandler, verify_webhook
+
+__version__ = "0.1.0"
+__all__ = [
+    # Clients
+    "Snippe",
+    "AsyncSnippe",
+    # Models
+    "Customer",
+    "Payment",
+    "PaymentDetails",
+    "PaymentList",
+    "Balance",
+    "WebhookPayload",
+    # Types
+    "PaymentType",
+    "PaymentStatus",
+    "Currency",
+    "WebhookEvent",
+    # Webhooks
+    "WebhookHandler",
+    "verify_webhook",
+    # Exceptions
+    "SnippeError",
+    "AuthenticationError",
+    "ValidationError",
+    "NotFoundError",
+    "RateLimitError",
+    "ServerError",
+    "WebhookVerificationError",
+]

snippe/client.py

@@ -0,0 +1,496 @@
+"""Snippe Payment API client."""
+
+import uuid
+from typing import Any, Optional
+
+import httpx
+
+from .exceptions import (
+    AuthenticationError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    SnippeError,
+    ValidationError,
+)
+from .models import Balance, Customer, Payment, PaymentDetails, PaymentList
+from .types import Currency, PaymentType
+
+
+class Snippe:
+    """
+    Snippe Payment API client.
+
+    Usage:
+        >>> from snippe import Snippe, Customer
+        >>> client = Snippe("your_api_key")
+        >>> payment = client.create_mobile_payment(
+        ...     amount=1000,
+        ...     currency="TZS",
+        ...     phone_number="0788500000",
+        ...     customer=Customer(firstname="John", lastname="Doe")
+        ... )
+    """
+
+    BASE_URL = "https://api.snippe.sh/api/v1"
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: Optional[str] = None,
+        timeout: float = 30.0,
+    ):
+        """
+        Initialize Snippe client.
+
+        Args:
+            api_key: Your Snippe API key
+            base_url: Override the base URL (for testing)
+            timeout: Request timeout in seconds
+        """
+        self.api_key = api_key
+        self.base_url = base_url or self.BASE_URL
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+            },
+            timeout=timeout,
+        )
+
+    def _handle_response(self, response: httpx.Response) -> dict:
+        """Handle API response and raise appropriate exceptions."""
+        try:
+            data = response.json()
+        except Exception:
+            data = {"message": response.text}
+
+        if response.status_code == 200 or response.status_code == 201:
+            return data.get("data", data)
+
+        message = data.get("message", "Unknown error")
+        error_code = data.get("error_code", "")
+        code = response.status_code
+
+        if code == 401:
+            raise AuthenticationError(message, code, error_code)
+        elif code == 400:
+            raise ValidationError(message, code, error_code)
+        elif code == 404:
+            raise NotFoundError(message, code, error_code)
+        elif code == 429:
+            raise RateLimitError(message, code, error_code)
+        elif code >= 500:
+            raise ServerError(message, code, error_code)
+        else:
+            raise SnippeError(message, code, error_code)
+
+    def _create_payment(
+        self,
+        payment_type: PaymentType,
+        amount: int,
+        currency: Currency,
+        phone_number: str,
+        customer: Customer,
+        callback_url: Optional[str] = None,
+        webhook_url: Optional[str] = None,
+        metadata: Optional[dict] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Payment:
+        """Internal method to create a payment."""
+        payload = {
+            "payment_type": payment_type,
+            "details": PaymentDetails(amount, currency, callback_url).to_dict(),
+            "phone_number": phone_number,
+            "customer": customer.to_dict(),
+        }
+        if webhook_url:
+            payload["webhook_url"] = webhook_url
+        if metadata:
+            payload["metadata"] = metadata
+
+        headers = {}
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+
+        response = self._client.post("/payments", json=payload, headers=headers)
+        data = self._handle_response(response)
+        return Payment.from_dict(data)
+
+    def create_mobile_payment(
+        self,
+        amount: int,
+        currency: Currency,
+        phone_number: str,
+        customer: Customer,
+        callback_url: Optional[str] = None,
+        webhook_url: Optional[str] = None,
+        metadata: Optional[dict] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Payment:
+        """
+        Create a mobile money payment (USSD push).
+
+        Customer receives a USSD prompt to confirm payment.
+
+        Args:
+            amount: Amount in smallest currency unit (e.g., cents)
+            currency: Currency code (TZS, KES, UGX)
+            phone_number: Customer phone number
+            customer: Customer information
+            callback_url: URL to redirect after payment
+            webhook_url: URL to receive payment status updates
+            metadata: Custom key-value pairs
+            idempotency_key: Unique key to prevent duplicates
+
+        Returns:
+            Payment object with reference and status
+        """
+        return self._create_payment(
+            payment_type="mobile",
+            amount=amount,
+            currency=currency,
+            phone_number=phone_number,
+            customer=customer,
+            callback_url=callback_url,
+            webhook_url=webhook_url,
+            metadata=metadata,
+            idempotency_key=idempotency_key,
+        )
+
+    def create_card_payment(
+        self,
+        amount: int,
+        currency: Currency,
+        phone_number: str,
+        customer: Customer,
+        callback_url: str,
+        webhook_url: Optional[str] = None,
+        metadata: Optional[dict] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Payment:
+        """
+        Create a card payment.
+
+        Returns a payment_url to redirect the customer.
+
+        Args:
+            amount: Amount in smallest currency unit
+            currency: Currency code (TZS, KES, UGX)
+            phone_number: Customer phone number
+            customer: Customer information (must include address fields)
+            callback_url: URL to redirect after payment (required)
+            webhook_url: URL to receive payment status updates
+            metadata: Custom key-value pairs
+            idempotency_key: Unique key to prevent duplicates
+
+        Returns:
+            Payment object with payment_url for redirect
+        """
+        return self._create_payment(
+            payment_type="card",
+            amount=amount,
+            currency=currency,
+            phone_number=phone_number,
+            customer=customer,
+            callback_url=callback_url,
+            webhook_url=webhook_url,
+            metadata=metadata,
+            idempotency_key=idempotency_key,
+        )
+
+    def create_qr_payment(
+        self,
+        amount: int,
+        currency: Currency,
+        phone_number: str,
+        customer: Customer,
+        callback_url: Optional[str] = None,
+        webhook_url: Optional[str] = None,
+        metadata: Optional[dict] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Payment:
+        """
+        Create a dynamic QR code payment.
+
+        Returns a QR code for the customer to scan.
+
+        Args:
+            amount: Amount in smallest currency unit
+            currency: Currency code (TZS, KES, UGX)
+            phone_number: Customer phone number
+            customer: Customer information
+            callback_url: URL to redirect after payment
+            webhook_url: URL to receive payment status updates
+            metadata: Custom key-value pairs
+            idempotency_key: Unique key to prevent duplicates
+
+        Returns:
+            Payment object with qr_code and payment_token
+        """
+        return self._create_payment(
+            payment_type="dynamic-qr",
+            amount=amount,
+            currency=currency,
+            phone_number=phone_number,
+            customer=customer,
+            callback_url=callback_url,
+            webhook_url=webhook_url,
+            metadata=metadata,
+            idempotency_key=idempotency_key,
+        )
+
+    def get_payment(self, reference: str) -> Payment:
+        """
+        Get payment status by reference.
+
+        Args:
+            reference: Payment reference from create response
+
+        Returns:
+            Payment object with current status
+        """
+        response = self._client.get(f"/payments/{reference}")
+        data = self._handle_response(response)
+        return Payment.from_dict(data)
+
+    def list_payments(
+        self,
+        limit: int = 20,
+        offset: int = 0,
+    ) -> PaymentList:
+        """
+        List all payments for your account.
+
+        Args:
+            limit: Results per page (max 100)
+            offset: Pagination offset
+
+        Returns:
+            PaymentList with payments and pagination info
+        """
+        response = self._client.get(
+            "/payments",
+            params={"limit": limit, "offset": offset},
+        )
+        data = self._handle_response(response)
+        return PaymentList.from_dict(data)
+
+    def get_balance(self) -> Balance:
+        """
+        Get your current account balance.
+
+        Returns:
+            Balance object with available and pending amounts
+        """
+        response = self._client.get("/payments/balance")
+        data = self._handle_response(response)
+        return Balance.from_dict(data)
+
+    def close(self) -> None:
+        """Close the HTTP client."""
+        self._client.close()
+
+    def __enter__(self) -> "Snippe":
+        return self
+
+    def __exit__(self, *args) -> None:
+        self.close()
+
+
+class AsyncSnippe:
+    """
+    Async Snippe Payment API client.
+
+    Usage:
+        >>> from snippe import AsyncSnippe, Customer
+        >>> async with AsyncSnippe("your_api_key") as client:
+        ...     payment = await client.create_mobile_payment(...)
+    """
+
+    BASE_URL = "https://api.snippe.sh/api/v1"
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: Optional[str] = None,
+        timeout: float = 30.0,
+    ):
+        """Initialize async Snippe client."""
+        self.api_key = api_key
+        self.base_url = base_url or self.BASE_URL
+        self._client = httpx.AsyncClient(
+            base_url=self.base_url,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+            },
+            timeout=timeout,
+        )
+
+    async def _handle_response(self, response: httpx.Response) -> dict:
+        """Handle API response and raise appropriate exceptions."""
+        try:
+            data = response.json()
+        except Exception:
+            data = {"message": response.text}
+
+        if response.status_code == 200 or response.status_code == 201:
+            return data.get("data", data)
+
+        message = data.get("message", "Unknown error")
+        error_code = data.get("error_code", "")
+        code = response.status_code
+
+        if code == 401:
+            raise AuthenticationError(message, code, error_code)
+        elif code == 400:
+            raise ValidationError(message, code, error_code)
+        elif code == 404:
+            raise NotFoundError(message, code, error_code)
+        elif code == 429:
+            raise RateLimitError(message, code, error_code)
+        elif code >= 500:
+            raise ServerError(message, code, error_code)
+        else:
+            raise SnippeError(message, code, error_code)
+
+    async def _create_payment(
+        self,
+        payment_type: PaymentType,
+        amount: int,
+        currency: Currency,
+        phone_number: str,
+        customer: Customer,
+        callback_url: Optional[str] = None,
+        webhook_url: Optional[str] = None,
+        metadata: Optional[dict] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Payment:
+        """Internal method to create a payment."""
+        payload = {
+            "payment_type": payment_type,
+            "details": PaymentDetails(amount, currency, callback_url).to_dict(),
+            "phone_number": phone_number,
+            "customer": customer.to_dict(),
+        }
+        if webhook_url:
+            payload["webhook_url"] = webhook_url
+        if metadata:
+            payload["metadata"] = metadata
+
+        headers = {}
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+
+        response = await self._client.post("/payments", json=payload, headers=headers)
+        data = await self._handle_response(response)
+        return Payment.from_dict(data)
+
+    async def create_mobile_payment(
+        self,
+        amount: int,
+        currency: Currency,
+        phone_number: str,
+        customer: Customer,
+        callback_url: Optional[str] = None,
+        webhook_url: Optional[str] = None,
+        metadata: Optional[dict] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Payment:
+        """Create a mobile money payment (USSD push)."""
+        return await self._create_payment(
+            payment_type="mobile",
+            amount=amount,
+            currency=currency,
+            phone_number=phone_number,
+            customer=customer,
+            callback_url=callback_url,
+            webhook_url=webhook_url,
+            metadata=metadata,
+            idempotency_key=idempotency_key,
+        )
+
+    async def create_card_payment(
+        self,
+        amount: int,
+        currency: Currency,
+        phone_number: str,
+        customer: Customer,
+        callback_url: str,
+        webhook_url: Optional[str] = None,
+        metadata: Optional[dict] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Payment:
+        """Create a card payment."""
+        return await self._create_payment(
+            payment_type="card",
+            amount=amount,
+            currency=currency,
+            phone_number=phone_number,
+            customer=customer,
+            callback_url=callback_url,
+            webhook_url=webhook_url,
+            metadata=metadata,
+            idempotency_key=idempotency_key,
+        )
+
+    async def create_qr_payment(
+        self,
+        amount: int,
+        currency: Currency,
+        phone_number: str,
+        customer: Customer,
+        callback_url: Optional[str] = None,
+        webhook_url: Optional[str] = None,
+        metadata: Optional[dict] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Payment:
+        """Create a dynamic QR code payment."""
+        return await self._create_payment(
+            payment_type="dynamic-qr",
+            amount=amount,
+            currency=currency,
+            phone_number=phone_number,
+            customer=customer,
+            callback_url=callback_url,
+            webhook_url=webhook_url,
+            metadata=metadata,
+            idempotency_key=idempotency_key,
+        )
+
+    async def get_payment(self, reference: str) -> Payment:
+        """Get payment status by reference."""
+        response = await self._client.get(f"/payments/{reference}")
+        data = await self._handle_response(response)
+        return Payment.from_dict(data)
+
+    async def list_payments(
+        self,
+        limit: int = 20,
+        offset: int = 0,
+    ) -> PaymentList:
+        """List all payments for your account."""
+        response = await self._client.get(
+            "/payments",
+            params={"limit": limit, "offset": offset},
+        )
+        data = await self._handle_response(response)
+        return PaymentList.from_dict(data)
+
+    async def get_balance(self) -> Balance:
+        """Get your current account balance."""
+        response = await self._client.get("/payments/balance")
+        data = await self._handle_response(response)
+        return Balance.from_dict(data)
+
+    async def close(self) -> None:
+        """Close the HTTP client."""
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncSnippe":
+        return self
+
+    async def __aexit__(self, *args) -> None:
+        await self.close()

snippe/exceptions.py

@@ -0,0 +1,41 @@
+"""Exceptions for Snippe SDK."""
+
+
+class SnippeError(Exception):
+    """Base exception for all Snippe errors."""
+
+    def __init__(self, message: str, code: int = 0, error_code: str = ""):
+        self.message = message
+        self.code = code
+        self.error_code = error_code
+        super().__init__(message)
+
+
+class AuthenticationError(SnippeError):
+    """Invalid or missing API key."""
+    pass
+
+
+class ValidationError(SnippeError):
+    """Invalid request parameters."""
+    pass
+
+
+class NotFoundError(SnippeError):
+    """Resource not found."""
+    pass
+
+
+class RateLimitError(SnippeError):
+    """Too many requests."""
+    pass
+
+
+class ServerError(SnippeError):
+    """Snippe server error."""
+    pass
+
+
+class WebhookVerificationError(SnippeError):
+    """Invalid webhook signature."""
+    pass

snippe/models.py

@@ -0,0 +1,165 @@
+"""Data models for Snippe SDK."""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Optional
+
+from .types import Currency, PaymentStatus, PaymentType, WebhookEvent
+
+
+@dataclass
+class Customer:
+    """Customer information."""
+    firstname: str
+    lastname: str
+    email: Optional[str] = None
+    address: Optional[str] = None
+    city: Optional[str] = None
+    state: Optional[str] = None
+    postcode: Optional[str] = None
+    country: Optional[str] = None
+    phone: Optional[str] = None
+
+    def to_dict(self) -> dict:
+        """Convert to API-compatible dict."""
+        data = {"firstname": self.firstname, "lastname": self.lastname}
+        if self.email:
+            data["email"] = self.email
+        if self.address:
+            data["address"] = self.address
+        if self.city:
+            data["city"] = self.city
+        if self.state:
+            data["state"] = self.state
+        if self.postcode:
+            data["postcode"] = self.postcode
+        if self.country:
+            data["country"] = self.country
+        return data
+
+
+@dataclass
+class PaymentDetails:
+    """Payment amount details."""
+    amount: int
+    currency: Currency
+    callback_url: Optional[str] = None
+
+    def to_dict(self) -> dict:
+        """Convert to API-compatible dict."""
+        data = {"amount": self.amount, "currency": self.currency}
+        if self.callback_url:
+            data["callback_url"] = self.callback_url
+        return data
+
+
+@dataclass
+class Payment:
+    """Payment response from API."""
+    reference: str
+    status: PaymentStatus
+    amount: int
+    currency: Currency
+    payment_type: PaymentType
+    expires_at: Optional[str] = None
+    payment_url: Optional[str] = None
+    qr_code: Optional[str] = None
+    payment_qr_code: Optional[str] = None
+    payment_token: Optional[str] = None
+    id: Optional[str] = None
+    psp_reference: Optional[str] = None
+    fee_amount: Optional[int] = None
+    net_amount: Optional[int] = None
+    customer: Optional[dict] = None
+    metadata: Optional[dict] = None
+    created_at: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Payment":
+        """Create Payment from API response dict."""
+        return cls(
+            reference=data["reference"],
+            status=data["status"],
+            amount=data["amount"],
+            currency=data["currency"],
+            payment_type=data["payment_type"],
+            expires_at=data.get("expires_at"),
+            payment_url=data.get("payment_url"),
+            qr_code=data.get("qr_code"),
+            payment_qr_code=data.get("payment_qr_code"),
+            payment_token=data.get("payment_token"),
+            id=data.get("id"),
+            psp_reference=data.get("psp_reference"),
+            fee_amount=data.get("fee_amount"),
+            net_amount=data.get("net_amount"),
+            customer=data.get("customer"),
+            metadata=data.get("metadata"),
+            created_at=data.get("created_at"),
+        )
+
+
+@dataclass
+class PaymentList:
+    """Paginated list of payments."""
+    payments: list[Payment]
+    limit: int
+    offset: int
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "PaymentList":
+        """Create PaymentList from API response dict."""
+        return cls(
+            payments=[Payment.from_dict(p) for p in data.get("payments", [])],
+            limit=data.get("limit", 20),
+            offset=data.get("offset", 0),
+        )
+
+
+@dataclass
+class Balance:
+    """Account balance."""
+    available_balance: int
+    balance: int
+    currency: Currency
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Balance":
+        """Create Balance from API response dict."""
+        return cls(
+            available_balance=data.get("available_balance", 0),
+            balance=data.get("balance", 0),
+            currency=data.get("currency", "TZS"),
+        )
+
+
+@dataclass
+class WebhookPayload:
+    """Webhook event payload."""
+    event: WebhookEvent
+    reference: str
+    status: PaymentStatus
+    amount: dict
+    payment_channel: str
+    payment_fee: int
+    customer: dict
+    metadata: dict
+    completed_at: Optional[str]
+    created_at: str
+    timestamp: int
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "WebhookPayload":
+        """Create WebhookPayload from webhook data."""
+        return cls(
+            event=data["event"],
+            reference=data["reference"],
+            status=data["status"],
+            amount=data["amount"],
+            payment_channel=data.get("payment_channel", ""),
+            payment_fee=data.get("payment_fee", 0),
+            customer=data.get("customer", {}),
+            metadata=data.get("metadata", {}),
+            completed_at=data.get("completed_at"),
+            created_at=data["created_at"],
+            timestamp=data["timestamp"],
+        )

snippe/types.py

@@ -0,0 +1,13 @@
+"""Type definitions for Snippe SDK."""
+
+from typing import Literal
+
+PaymentType = Literal["mobile", "card", "dynamic-qr"]
+PaymentStatus = Literal["pending", "completed", "failed", "expired", "voided"]
+Currency = Literal["TZS", "KES", "UGX"]
+WebhookEvent = Literal[
+    "payment.completed",
+    "payment.failed",
+    "payment.expired",
+    "payment.voided"
+]

snippe/webhooks.py

@@ -0,0 +1,159 @@
+"""Webhook verification utilities for Snippe SDK."""
+
+import hashlib
+import hmac
+import time
+from typing import Optional
+
+from .exceptions import WebhookVerificationError
+from .models import WebhookPayload
+
+
+class WebhookHandler:
+    """
+    Webhook handler for verifying and parsing Snippe webhooks.
+
+    Usage:
+        >>> from snippe import WebhookHandler
+        >>> handler = WebhookHandler("your_webhook_signing_key")
+        >>> payload = handler.verify_and_parse(
+        ...     body=request.body,
+        ...     signature=request.headers["X-Webhook-Signature"],
+        ...     timestamp=request.headers["X-Webhook-Timestamp"]
+        ... )
+    """
+
+    def __init__(
+        self,
+        signing_key: str,
+        tolerance: int = 300,
+    ):
+        """
+        Initialize webhook handler.
+
+        Args:
+            signing_key: Your webhook signing key
+            tolerance: Max age in seconds for webhook (default: 5 minutes)
+        """
+        self.signing_key = signing_key
+        self.tolerance = tolerance
+
+    def compute_signature(self, payload: str, timestamp: str) -> str:
+        """
+        Compute HMAC-SHA256 signature for payload.
+
+        Args:
+            payload: Raw request body as string
+            timestamp: Unix timestamp from X-Webhook-Timestamp header
+
+        Returns:
+            Hex-encoded signature
+        """
+        message = f"{timestamp}.{payload}"
+        signature = hmac.new(
+            self.signing_key.encode(),
+            message.encode(),
+            hashlib.sha256,
+        )
+        return signature.hexdigest()
+
+    def verify_signature(
+        self,
+        payload: str,
+        signature: str,
+        timestamp: str,
+    ) -> bool:
+        """
+        Verify webhook signature.
+
+        Args:
+            payload: Raw request body as string
+            signature: Value from X-Webhook-Signature header
+            timestamp: Value from X-Webhook-Timestamp header
+
+        Returns:
+            True if signature is valid
+
+        Raises:
+            WebhookVerificationError: If signature is invalid or expired
+        """
+        # Check timestamp to prevent replay attacks
+        try:
+            ts = int(timestamp)
+        except (ValueError, TypeError):
+            raise WebhookVerificationError("Invalid timestamp")
+
+        if abs(time.time() - ts) > self.tolerance:
+            raise WebhookVerificationError("Webhook timestamp expired")
+
+        # Compute and compare signatures
+        expected = self.compute_signature(payload, timestamp)
+        if not hmac.compare_digest(expected, signature):
+            raise WebhookVerificationError("Invalid signature")
+
+        return True
+
+    def parse(self, data: dict) -> WebhookPayload:
+        """
+        Parse webhook payload without verification.
+
+        Args:
+            data: Parsed JSON payload
+
+        Returns:
+            WebhookPayload object
+        """
+        return WebhookPayload.from_dict(data)
+
+    def verify_and_parse(
+        self,
+        body: str,
+        signature: str,
+        timestamp: str,
+    ) -> WebhookPayload:
+        """
+        Verify signature and parse webhook payload.
+
+        Args:
+            body: Raw request body as string
+            signature: Value from X-Webhook-Signature header
+            timestamp: Value from X-Webhook-Timestamp header
+
+        Returns:
+            WebhookPayload object
+
+        Raises:
+            WebhookVerificationError: If signature is invalid or expired
+        """
+        import json
+
+        self.verify_signature(body, signature, timestamp)
+        data = json.loads(body)
+        return self.parse(data)
+
+
+def verify_webhook(
+    body: str,
+    signature: str,
+    timestamp: str,
+    signing_key: str,
+    tolerance: int = 300,
+) -> WebhookPayload:
+    """
+    Convenience function to verify and parse a webhook.
+
+    Args:
+        body: Raw request body as string
+        signature: Value from X-Webhook-Signature header
+        timestamp: Value from X-Webhook-Timestamp header
+        signing_key: Your webhook signing key
+        tolerance: Max age in seconds (default: 5 minutes)
+
+    Returns:
+        WebhookPayload object
+
+    Raises:
+        WebhookVerificationError: If signature is invalid or expired
+    """
+    handler = WebhookHandler(signing_key, tolerance)
+    return handler.verify_and_parse(body, signature, timestamp)

snippe-0.1.0.dist-info/METADATA

@@ -0,0 +1,249 @@
+Metadata-Version: 2.4
+Name: snippe
+Version: 0.1.0
+Summary: Official Python SDK for Snippe Payment API
+Project-URL: Homepage, https://snippe.sh
+Project-URL: Documentation, https://documenter.getpostman.com/view/36488510/2sBXViiWAV#6beb6d54-34a1-4c9c-8a19-acd92a865711
+Project-URL: Repository, https://github.com/Neurotech-HQ/snippe-python-sdk
+Author-email: Nassdaq <mwaijegakelvin@gmail.com>
+License-Expression: MIT
+Keywords: Tanzania Payment,africa,fintech,mobile-money,snippe
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: respx>=0.20.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Snippe Python SDK
+
+Official Python SDK for [Snippe Payment API](https://snippe.sh) - Accept payments via mobile money, card, and QR code in East Africa.
+
+## Installation
+
+```bash
+pip install snippe
+```
+
+## Quick Start
+
+```python
+from snippe import Snippe, Customer
+
+client = Snippe("your_api_key")
+
+# Create a mobile money payment
+payment = client.create_mobile_payment(
+    amount=1000,
+    currency="TZS",
+    phone_number="0788500000",
+    customer=Customer(firstname="John", lastname="Doe"),
+)
+
+print(f"Payment reference: {payment.reference}")
+print(f"Status: {payment.status}")
+```
+
+## Payment Types
+
+### Mobile Money (USSD Push)
+
+Customer receives a USSD prompt on their phone to confirm payment.
+
+```python
+payment = client.create_mobile_payment(
+    amount=5000,
+    currency="TZS",
+    phone_number="0712345678",
+    customer=Customer(
+        firstname="Jane",
+        lastname="Doe",
+        email="jane@example.com"  # optional
+    ),
+    webhook_url="https://yourapp.com/webhooks",  # optional
+    metadata={"order_id": "ORD-123"},  # optional
+)
+```
+
+### Card Payment
+
+Returns a `payment_url` to redirect the customer to complete payment.
+
+```python
+payment = client.create_card_payment(
+    amount=50000,
+    currency="TZS",
+    phone_number="0712345678",
+    customer=Customer(
+        firstname="John",
+        lastname="Doe",
+        email="john@example.com",
+        address="123 Main Street",
+        city="Dar es Salaam",
+        state="DSM",
+        postcode="14101",
+        country="TZ",
+    ),
+    callback_url="https://yourapp.com/callback",  # required for card
+    webhook_url="https://yourapp.com/webhooks",
+)
+
+# Redirect customer to this URL
+print(payment.payment_url)
+```
+
+### QR Code Payment
+
+Returns a QR code for the customer to scan.
+
+```python
+payment = client.create_qr_payment(
+    amount=25000,
+    currency="TZS",
+    phone_number="0712345678",
+    customer=Customer(firstname="John", lastname="Doe"),
+)
+
+# Display this QR code to customer
+print(payment.payment_qr_code)
+print(payment.payment_token)
+```
+
+## Check Payment Status
+
+```python
+payment = client.get_payment("payment_reference")
+print(f"Status: {payment.status}")  # pending, completed, failed, expired, voided
+```
+
+## List Payments
+
+```python
+result = client.list_payments(limit=20, offset=0)
+for payment in result.payments:
+    print(f"{payment.reference}: {payment.status}")
+```
+
+## Check Balance
+
+```python
+balance = client.get_balance()
+print(f"Available: {balance.available_balance} {balance.currency}")
+```
+
+## Webhooks
+
+Verify and parse webhook events from Snippe.
+
+```python
+from snippe import verify_webhook, WebhookVerificationError
+
+# In your webhook endpoint
+try:
+    payload = verify_webhook(
+        body=request.body.decode(),
+        signature=request.headers["X-Webhook-Signature"],
+        timestamp=request.headers["X-Webhook-Timestamp"],
+        signing_key="your_webhook_signing_key",
+    )
+
+    if payload.event == "payment.completed":
+        print(f"Payment {payload.reference} completed!")
+        # Fulfill the order
+    elif payload.event == "payment.failed":
+        print(f"Payment {payload.reference} failed")
+        # Notify customer
+
+except WebhookVerificationError as e:
+    print(f"Invalid webhook: {e}")
+```
+
+### Webhook Events
+
+| Event | Description |
+|-------|-------------|
+| `payment.completed` | Payment successful |
+| `payment.failed` | Payment declined or failed |
+| `payment.expired` | Payment timed out |
+| `payment.voided` | Payment cancelled |
+
+## Async Support
+
+For async applications (FastAPI, aiohttp, etc.):
+
+```python
+from snippe import AsyncSnippe, Customer
+
+async def create_payment():
+    async with AsyncSnippe("your_api_key") as client:
+        payment = await client.create_mobile_payment(
+            amount=1000,
+            currency="TZS",
+            phone_number="0788500000",
+            customer=Customer(firstname="John", lastname="Doe"),
+        )
+        return payment
+```
+
+## Idempotency
+
+Prevent duplicate payments by providing an idempotency key:
+
+```python
+payment = client.create_mobile_payment(
+    amount=1000,
+    currency="TZS",
+    phone_number="0788500000",
+    customer=Customer(firstname="John", lastname="Doe"),
+    idempotency_key="unique_order_id_123",  # Your unique identifier
+)
+```
+
+## Error Handling
+
+```python
+from snippe import (
+    Snippe,
+    AuthenticationError,
+    ValidationError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+)
+
+try:
+    payment = client.create_mobile_payment(...)
+except AuthenticationError:
+    print("Invalid API key")
+except ValidationError as e:
+    print(f"Invalid request: {e.message}")
+except NotFoundError:
+    print("Payment not found")
+except RateLimitError:
+    print("Too many requests, slow down")
+except ServerError:
+    print("Snippe server error, try again later")
+```
+
+## Supported Currencies
+
+| Currency | Country |
+|----------|---------|
+| TZS | Tanzania |
+| KES | Kenya |
+| UGX | Uganda |
+
+## License
+
+MIT

snippe-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+snippe/__init__.py,sha256=kBzciBjF9_R2aM2Mof5Z6EX9iUUw8VTOTREm3srLa90,1440
+snippe/client.py,sha256=JmWbYm4tzUDea2cfcZygjsJUooQ_Tejtvn0ZsOZZKNk,15535
+snippe/exceptions.py,sha256=N444s_aLPnElQVU9EqSmXskvegB72B221i0E1wuAN-8,807
+snippe/models.py,sha256=cDfUNaFWtqvfsJnlKgwvtHU31h8tZrypC_JVL-YJtq4,4852
+snippe/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+snippe/types.py,sha256=RN-Gvr3hGFlhrmjTftcN3nw8G6EBaD9mMZbd_nkKM9Q,358
+snippe/webhooks.py,sha256=OVhEcoWeM3A7arqPQl0JuCshTlgIuADD7cysVghSqR0,4352
+snippe-0.1.0.dist-info/METADATA,sha256=4HPXC8s3hL6zo_1YCi2_HhEFSD0OJ2X-4cbwWV1EsGY,6203
+snippe-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+snippe-0.1.0.dist-info/RECORD,,

snippe-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any