payplus-python 0.1.2__py3-none-any.whl

payplus/client.py

@@ -0,0 +1,211 @@
+"""
+PayPlus API Client - Core HTTP client for PayPlus payment gateway.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+from typing import Any, Optional
+
+import httpx
+
+from payplus.api.payments import PaymentsAPI
+from payplus.api.recurring import RecurringAPI
+from payplus.api.transactions import TransactionsAPI
+from payplus.api.payment_pages import PaymentPagesAPI
+from payplus.exceptions import PayPlusError, PayPlusAPIError, PayPlusAuthError
+
+
+class PayPlus:
+    """
+    PayPlus API client.
+    
+    Usage:
+        client = PayPlus(
+            api_key="your_api_key",
+            secret_key="your_secret_key",
+            terminal_uid="your_terminal_uid"
+        )
+        
+        # Generate a payment link
+        link = client.payment_pages.generate_link(
+            amount=100.00,
+            currency="ILS",
+            description="Monthly subscription"
+        )
+    """
+    
+    BASE_URL = "https://restapi.payplus.co.il/api/v1.0"
+    SANDBOX_URL = "https://restapidev.payplus.co.il/api/v1.0"
+    
+    def __init__(
+        self,
+        api_key: str,
+        secret_key: str,
+        terminal_uid: Optional[str] = None,
+        sandbox: bool = False,
+        timeout: float = 30.0,
+    ):
+        """
+        Initialize PayPlus client.
+        
+        Args:
+            api_key: PayPlus API key
+            secret_key: PayPlus secret key
+            terminal_uid: Terminal UID (optional, uses default if not provided)
+            sandbox: Use sandbox environment
+            timeout: Request timeout in seconds
+        """
+        self.api_key = api_key
+        self.secret_key = secret_key
+        self.terminal_uid = terminal_uid
+        self.sandbox = sandbox
+        self.base_url = self.SANDBOX_URL if sandbox else self.BASE_URL
+        
+        self._client = httpx.Client(
+            timeout=timeout,
+            headers=self._get_headers(),
+        )
+        
+        self._async_client: Optional[httpx.AsyncClient] = None
+        
+        # API endpoints
+        self.payments = PaymentsAPI(self)
+        self.recurring = RecurringAPI(self)
+        self.transactions = TransactionsAPI(self)
+        self.payment_pages = PaymentPagesAPI(self)
+    
+    def _get_headers(self) -> dict[str, str]:
+        """Get default headers for API requests."""
+        return {
+            "Content-Type": "application/json",
+            "Authorization": json.dumps({
+                "api_key": self.api_key,
+                "secret_key": self.secret_key,
+            }),
+        }
+    
+    @property
+    def async_client(self) -> httpx.AsyncClient:
+        """Get or create async HTTP client."""
+        if self._async_client is None:
+            self._async_client = httpx.AsyncClient(
+                timeout=30.0,
+                headers=self._get_headers(),
+            )
+        return self._async_client
+    
+    def _request(
+        self,
+        method: str,
+        endpoint: str,
+        data: Optional[dict[str, Any]] = None,
+        params: Optional[dict[str, Any]] = None,
+    ) -> dict[str, Any]:
+        """Make a synchronous API request."""
+        url = f"{self.base_url}/{endpoint}"
+        
+        try:
+            response = self._client.request(
+                method=method,
+                url=url,
+                json=data,
+                params=params,
+            )
+            return self._handle_response(response)
+        except httpx.HTTPError as e:
+            raise PayPlusError(f"HTTP error: {e}") from e
+    
+    async def _async_request(
+        self,
+        method: str,
+        endpoint: str,
+        data: Optional[dict[str, Any]] = None,
+        params: Optional[dict[str, Any]] = None,
+    ) -> dict[str, Any]:
+        """Make an asynchronous API request."""
+        url = f"{self.base_url}/{endpoint}"
+        
+        try:
+            response = await self.async_client.request(
+                method=method,
+                url=url,
+                json=data,
+                params=params,
+            )
+            return self._handle_response(response)
+        except httpx.HTTPError as e:
+            raise PayPlusError(f"HTTP error: {e}") from e
+    
+    def _handle_response(self, response: httpx.Response) -> dict[str, Any]:
+        """Handle API response."""
+        try:
+            data = response.json()
+        except json.JSONDecodeError:
+            raise PayPlusError(f"Invalid JSON response: {response.text}")
+        
+        if response.status_code == 401:
+            raise PayPlusAuthError("Authentication failed. Check your API credentials.")
+        
+        if response.status_code >= 400:
+            error_msg = data.get("message") or data.get("error") or str(data)
+            raise PayPlusAPIError(
+                message=error_msg,
+                status_code=response.status_code,
+                response=data,
+            )
+        
+        # PayPlus specific error handling
+        if isinstance(data, dict):
+            results = data.get("results", {})
+            if isinstance(results, dict) and results.get("status") == "error":
+                raise PayPlusAPIError(
+                    message=results.get("description", "Unknown error"),
+                    status_code=response.status_code,
+                    response=data,
+                )
+        
+        return data
+    
+    def verify_webhook_signature(
+        self,
+        payload: bytes,
+        signature: str,
+    ) -> bool:
+        """
+        Verify webhook/IPN signature.
+        
+        Args:
+            payload: Raw request body
+            signature: Signature from X-PayPlus-Signature header
+            
+        Returns:
+            True if signature is valid
+        """
+        expected = hmac.new(
+            self.secret_key.encode(),
+            payload,
+            hashlib.sha256,
+        ).hexdigest()
+        return hmac.compare_digest(expected, signature)
+    
+    def close(self) -> None:
+        """Close HTTP clients."""
+        self._client.close()
+        if self._async_client:
+            # Note: for async client, use await client.aclose() in async context
+            pass
+    
+    async def aclose(self) -> None:
+        """Close async HTTP client."""
+        if self._async_client:
+            await self._async_client.aclose()
+            self._async_client = None
+    
+    def __enter__(self) -> "PayPlus":
+        return self
+    
+    def __exit__(self, *args: Any) -> None:
+        self.close()

payplus/exceptions.py

@@ -0,0 +1,57 @@
+"""
+PayPlus SDK Exceptions.
+"""
+
+from typing import Any, Optional
+
+
+class PayPlusError(Exception):
+    """Base exception for PayPlus SDK."""
+    pass
+
+
+class PayPlusAPIError(PayPlusError):
+    """Exception raised for API errors."""
+    
+    def __init__(
+        self,
+        message: str,
+        status_code: Optional[int] = None,
+        response: Optional[dict[str, Any]] = None,
+    ):
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.response = response or {}
+    
+    def __str__(self) -> str:
+        if self.status_code:
+            return f"[{self.status_code}] {self.message}"
+        return self.message
+
+
+class PayPlusAuthError(PayPlusAPIError):
+    """Exception raised for authentication errors."""
+    
+    def __init__(self, message: str = "Authentication failed"):
+        super().__init__(message, status_code=401)
+
+
+class PayPlusValidationError(PayPlusError):
+    """Exception raised for validation errors."""
+    pass
+
+
+class SubscriptionError(PayPlusError):
+    """Exception raised for subscription-related errors."""
+    pass
+
+
+class WebhookError(PayPlusError):
+    """Exception raised for webhook-related errors."""
+    pass
+
+
+class WebhookSignatureError(WebhookError):
+    """Exception raised when webhook signature verification fails."""
+    pass

payplus/models/__init__.py

@@ -0,0 +1,23 @@
+"""
+PayPlus SDK Models for subscription management.
+"""
+
+from payplus.models.customer import Customer
+from payplus.models.subscription import Subscription, SubscriptionStatus, BillingCycle
+from payplus.models.payment import Payment, PaymentStatus
+from payplus.models.invoice import Invoice, InvoiceStatus, InvoiceItem
+from payplus.models.tier import Tier, TierFeature
+
+__all__ = [
+    "Customer",
+    "Subscription",
+    "SubscriptionStatus",
+    "BillingCycle",
+    "Payment",
+    "PaymentStatus",
+    "Invoice",
+    "InvoiceStatus",
+    "InvoiceItem",
+    "Tier",
+    "TierFeature",
+]

payplus/models/customer.py

@@ -0,0 +1,136 @@
+"""
+Customer model for subscription management.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Optional, Any
+from enum import Enum
+
+from pydantic import BaseModel, Field, EmailStr
+
+
+class CustomerStatus(str, Enum):
+    """Customer status."""
+    ACTIVE = "active"
+    INACTIVE = "inactive"
+    SUSPENDED = "suspended"
+
+
+class PaymentMethod(BaseModel):
+    """Stored payment method (tokenized card)."""
+    
+    id: str = Field(..., description="Payment method ID")
+    token: str = Field(..., description="PayPlus card token (card_uid)")
+    card_brand: Optional[str] = Field(None, description="Card brand (Visa, Mastercard, etc.)")
+    last_four: Optional[str] = Field(None, description="Last 4 digits of card")
+    expiry_month: Optional[str] = Field(None, description="Card expiry month")
+    expiry_year: Optional[str] = Field(None, description="Card expiry year")
+    holder_name: Optional[str] = Field(None, description="Card holder name")
+    is_default: bool = Field(default=False, description="Default payment method")
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class Customer(BaseModel):
+    """
+    Customer model for subscription management.
+    
+    This model tracks customer information, payment methods, and links to
+    subscriptions and invoices.
+    """
+    
+    id: str = Field(..., description="Unique customer ID")
+    email: EmailStr = Field(..., description="Customer email")
+    name: Optional[str] = Field(None, description="Customer full name")
+    phone: Optional[str] = Field(None, description="Customer phone")
+    company: Optional[str] = Field(None, description="Company name")
+    
+    # PayPlus integration
+    payplus_customer_uid: Optional[str] = Field(None, description="PayPlus customer UID")
+    
+    # Payment methods
+    payment_methods: list[PaymentMethod] = Field(default_factory=list)
+    default_payment_method_id: Optional[str] = Field(None)
+    
+    # Status
+    status: CustomerStatus = Field(default=CustomerStatus.ACTIVE)
+    
+    # Address
+    address_line1: Optional[str] = None
+    address_line2: Optional[str] = None
+    city: Optional[str] = None
+    state: Optional[str] = None
+    postal_code: Optional[str] = None
+    country: Optional[str] = Field(default="IL")
+    
+    # Tax
+    tax_id: Optional[str] = Field(None, description="Tax ID / VAT number")
+    
+    # Metadata
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    
+    # Timestamps
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    updated_at: datetime = Field(default_factory=datetime.utcnow)
+    
+    def get_default_payment_method(self) -> Optional[PaymentMethod]:
+        """Get the default payment method."""
+        if self.default_payment_method_id:
+            for pm in self.payment_methods:
+                if pm.id == self.default_payment_method_id:
+                    return pm
+        # Return first payment method if no default set
+        if self.payment_methods:
+            return self.payment_methods[0]
+        return None
+    
+    def add_payment_method(
+        self,
+        token: str,
+        card_brand: Optional[str] = None,
+        last_four: Optional[str] = None,
+        expiry_month: Optional[str] = None,
+        expiry_year: Optional[str] = None,
+        holder_name: Optional[str] = None,
+        set_default: bool = True,
+    ) -> PaymentMethod:
+        """Add a new payment method."""
+        import uuid
+        
+        pm = PaymentMethod(
+            id=str(uuid.uuid4()),
+            token=token,
+            card_brand=card_brand,
+            last_four=last_four,
+            expiry_month=expiry_month,
+            expiry_year=expiry_year,
+            holder_name=holder_name,
+            is_default=set_default,
+        )
+        
+        if set_default:
+            for existing in self.payment_methods:
+                existing.is_default = False
+            self.default_payment_method_id = pm.id
+        
+        self.payment_methods.append(pm)
+        self.updated_at = datetime.utcnow()
+        return pm
+    
+    def remove_payment_method(self, payment_method_id: str) -> bool:
+        """Remove a payment method."""
+        for i, pm in enumerate(self.payment_methods):
+            if pm.id == payment_method_id:
+                self.payment_methods.pop(i)
+                if self.default_payment_method_id == payment_method_id:
+                    self.default_payment_method_id = (
+                        self.payment_methods[0].id if self.payment_methods else None
+                    )
+                self.updated_at = datetime.utcnow()
+                return True
+        return False
+    
+    class Config:
+        use_enum_values = True

payplus/models/invoice.py

@@ -0,0 +1,242 @@
+"""
+Invoice model for billing and record-keeping.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, date
+from typing import Optional, Any
+from decimal import Decimal
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+
+class InvoiceStatus(str, Enum):
+    """Invoice status."""
+    DRAFT = "draft"
+    OPEN = "open"
+    PAID = "paid"
+    VOID = "void"
+    UNCOLLECTIBLE = "uncollectible"
+
+
+class InvoiceItem(BaseModel):
+    """Line item on an invoice."""
+    
+    id: str = Field(..., description="Line item ID")
+    description: str = Field(..., description="Item description")
+    quantity: int = Field(default=1)
+    unit_amount: Decimal = Field(..., description="Price per unit")
+    amount: Decimal = Field(..., description="Total line amount")
+    currency: str = Field(default="ILS")
+    
+    # Period for subscription items
+    period_start: Optional[datetime] = None
+    period_end: Optional[datetime] = None
+    
+    # References
+    subscription_id: Optional[str] = None
+    tier_id: Optional[str] = None
+    
+    # Proration
+    proration: bool = Field(default=False)
+    
+    # Metadata
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class InvoiceDiscount(BaseModel):
+    """Discount applied to an invoice."""
+    
+    id: str
+    name: str
+    amount: Decimal
+    percent_off: Optional[Decimal] = None
+    coupon_code: Optional[str] = None
+
+
+class Invoice(BaseModel):
+    """
+    Invoice model for billing and record-keeping.
+    
+    Invoices are generated for subscription renewals and one-time charges.
+    """
+    
+    id: str = Field(..., description="Unique invoice ID")
+    number: Optional[str] = Field(None, description="Invoice number for display")
+    customer_id: str = Field(..., description="Customer ID")
+    subscription_id: Optional[str] = Field(None, description="Subscription ID if recurring")
+    
+    # Status
+    status: InvoiceStatus = Field(default=InvoiceStatus.DRAFT)
+    
+    # Line items
+    items: list[InvoiceItem] = Field(default_factory=list)
+    
+    # Amounts
+    subtotal: Decimal = Field(default=Decimal("0"))
+    tax: Decimal = Field(default=Decimal("0"))
+    tax_percent: Optional[Decimal] = Field(None, description="Tax percentage")
+    total: Decimal = Field(default=Decimal("0"))
+    amount_due: Decimal = Field(default=Decimal("0"))
+    amount_paid: Decimal = Field(default=Decimal("0"))
+    amount_remaining: Decimal = Field(default=Decimal("0"))
+    currency: str = Field(default="ILS")
+    
+    # Discounts
+    discounts: list[InvoiceDiscount] = Field(default_factory=list)
+    total_discount: Decimal = Field(default=Decimal("0"))
+    
+    # Payment
+    payment_id: Optional[str] = Field(None, description="Payment ID when paid")
+    payment_intent: Optional[str] = None
+    
+    # Billing
+    billing_reason: Optional[str] = Field(None, description="subscription_create, subscription_cycle, etc.")
+    
+    # Period
+    period_start: Optional[datetime] = None
+    period_end: Optional[datetime] = None
+    
+    # Due date
+    due_date: Optional[date] = None
+    
+    # Customer details snapshot
+    customer_email: Optional[str] = None
+    customer_name: Optional[str] = None
+    customer_address: Optional[dict[str, str]] = None
+    customer_tax_id: Optional[str] = None
+    
+    # URLs
+    hosted_invoice_url: Optional[str] = None
+    pdf_url: Optional[str] = None
+    
+    # Collection
+    collection_method: str = Field(default="charge_automatically")
+    auto_advance: bool = Field(default=True)
+    attempt_count: int = Field(default=0)
+    next_payment_attempt: Optional[datetime] = None
+    
+    # Metadata
+    memo: Optional[str] = None
+    footer: Optional[str] = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    
+    # Timestamps
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    updated_at: datetime = Field(default_factory=datetime.utcnow)
+    finalized_at: Optional[datetime] = None
+    paid_at: Optional[datetime] = None
+    voided_at: Optional[datetime] = None
+    
+    def add_item(
+        self,
+        item_id: str,
+        description: str,
+        unit_amount: Decimal,
+        quantity: int = 1,
+        **kwargs: Any,
+    ) -> InvoiceItem:
+        """Add a line item to the invoice."""
+        amount = unit_amount * quantity
+        
+        item = InvoiceItem(
+            id=item_id,
+            description=description,
+            quantity=quantity,
+            unit_amount=unit_amount,
+            amount=amount,
+            currency=self.currency,
+            **kwargs,
+        )
+        
+        self.items.append(item)
+        self._recalculate_totals()
+        return item
+    
+    def add_discount(
+        self,
+        discount_id: str,
+        name: str,
+        amount: Optional[Decimal] = None,
+        percent_off: Optional[Decimal] = None,
+        coupon_code: Optional[str] = None,
+    ) -> InvoiceDiscount:
+        """Add a discount to the invoice."""
+        if percent_off:
+            calculated_amount = self.subtotal * (percent_off / 100)
+        elif amount:
+            calculated_amount = amount
+        else:
+            calculated_amount = Decimal("0")
+        
+        discount = InvoiceDiscount(
+            id=discount_id,
+            name=name,
+            amount=calculated_amount,
+            percent_off=percent_off,
+            coupon_code=coupon_code,
+        )
+        
+        self.discounts.append(discount)
+        self._recalculate_totals()
+        return discount
+    
+    def _recalculate_totals(self) -> None:
+        """Recalculate invoice totals."""
+        self.subtotal = sum(item.amount for item in self.items)
+        self.total_discount = sum(d.amount for d in self.discounts)
+        
+        taxable = self.subtotal - self.total_discount
+        if self.tax_percent:
+            self.tax = taxable * (self.tax_percent / 100)
+        
+        self.total = taxable + self.tax
+        self.amount_remaining = self.total - self.amount_paid
+        self.amount_due = self.amount_remaining
+        self.updated_at = datetime.utcnow()
+    
+    def finalize(self) -> None:
+        """Finalize the invoice (make it ready for payment)."""
+        if self.status != InvoiceStatus.DRAFT:
+            return
+        
+        self._recalculate_totals()
+        self.status = InvoiceStatus.OPEN
+        self.finalized_at = datetime.utcnow()
+        self.updated_at = datetime.utcnow()
+    
+    def mark_paid(self, payment_id: str) -> None:
+        """Mark the invoice as paid."""
+        self.status = InvoiceStatus.PAID
+        self.payment_id = payment_id
+        self.amount_paid = self.total
+        self.amount_remaining = Decimal("0")
+        self.amount_due = Decimal("0")
+        self.paid_at = datetime.utcnow()
+        self.updated_at = datetime.utcnow()
+    
+    def void(self) -> None:
+        """Void the invoice."""
+        self.status = InvoiceStatus.VOID
+        self.voided_at = datetime.utcnow()
+        self.updated_at = datetime.utcnow()
+    
+    def mark_uncollectible(self) -> None:
+        """Mark invoice as uncollectible."""
+        self.status = InvoiceStatus.UNCOLLECTIBLE
+        self.updated_at = datetime.utcnow()
+    
+    @property
+    def is_paid(self) -> bool:
+        """Check if invoice is paid."""
+        return self.status == InvoiceStatus.PAID
+    
+    @property
+    def is_open(self) -> bool:
+        """Check if invoice is open for payment."""
+        return self.status == InvoiceStatus.OPEN
+    
+    class Config:
+        use_enum_values = True