payplus-python 0.1.2__py3-none-any.whl

examples/basic_payment.py

@@ -0,0 +1,29 @@
+"""
+Basic payment example - Generate a payment link.
+"""
+
+import os
+from payplus import PayPlus
+
+# Initialize client
+client = PayPlus(
+    api_key=os.environ.get("PAYPLUS_API_KEY", "your_api_key"),
+    secret_key=os.environ.get("PAYPLUS_SECRET_KEY", "your_secret_key"),
+    sandbox=True,  # Use sandbox for testing
+)
+
+# Generate a payment link
+result = client.payment_pages.generate_link(
+    amount=100.00,
+    currency="ILS",
+    description="Test Payment",
+    customer_email="test@example.com",
+    customer_name="Test User",
+    success_url="https://example.com/success",
+    failure_url="https://example.com/failure",
+    create_token=True,  # Save card for future use
+)
+
+print("Payment Link Generated:")
+print(f"URL: {result.get('data', {}).get('payment_page_link')}")
+print(f"Request UID: {result.get('data', {}).get('page_request_uid')}")

examples/fastapi_webhooks.py

@@ -0,0 +1,130 @@
+"""
+FastAPI webhook handling example.
+"""
+
+import os
+from fastapi import FastAPI, Request, HTTPException
+from payplus import PayPlus
+from payplus.webhooks import WebhookHandler, WebhookSignatureError
+
+app = FastAPI(title="PayPlus Webhook Example")
+
+# Initialize PayPlus client
+client = PayPlus(
+    api_key=os.environ.get("PAYPLUS_API_KEY", "your_api_key"),
+    secret_key=os.environ.get("PAYPLUS_SECRET_KEY", "your_secret_key"),
+)
+
+# Initialize webhook handler
+webhooks = WebhookHandler(client, verify_signature=True)
+
+
+# Register event handlers
+@webhooks.on("payment.success")
+async def handle_payment_success(event):
+    """Handle successful payment."""
+    print(f"✅ Payment succeeded!")
+    print(f"   Transaction: {event.transaction_uid}")
+    print(f"   Amount: {event.amount} {event.currency}")
+    print(f"   Customer: {event.customer_email}")
+    
+    # Your business logic here:
+    # - Update order status
+    # - Send confirmation email
+    # - Provision service
+    # - etc.
+
+
+@webhooks.on("payment.failure")
+async def handle_payment_failure(event):
+    """Handle failed payment."""
+    print(f"❌ Payment failed!")
+    print(f"   Error: {event.status_description}")
+    print(f"   Customer: {event.customer_email}")
+    
+    # Your business logic here:
+    # - Update order status
+    # - Send notification email
+    # - Log for analysis
+
+
+@webhooks.on("recurring.charged")
+async def handle_recurring_charge(event):
+    """Handle recurring payment charge."""
+    print(f"🔄 Recurring payment charged!")
+    print(f"   Recurring UID: {event.recurring_uid}")
+    print(f"   Amount: {event.amount} {event.currency}")
+    
+    # Your business logic here:
+    # - Extend subscription
+    # - Create invoice
+    # - Send receipt
+
+
+@webhooks.on("recurring.failed")
+async def handle_recurring_failure(event):
+    """Handle recurring payment failure."""
+    print(f"⚠️ Recurring payment failed!")
+    print(f"   Recurring UID: {event.recurring_uid}")
+    print(f"   Error: {event.status_description}")
+    
+    # Your business logic here:
+    # - Mark subscription as past_due
+    # - Send dunning email
+    # - Schedule retry
+
+
+@webhooks.on("token.created")
+async def handle_token_created(event):
+    """Handle new card token."""
+    print(f"💳 Card tokenized!")
+    print(f"   Token: {event.card_uid}")
+    print(f"   Brand: {event.card_brand}")
+    print(f"   Last 4: {event.card_last_four}")
+    
+    # Your business logic here:
+    # - Save token to customer profile
+    # - Update payment method
+
+
+@webhooks.on("*")
+async def handle_all_events(event):
+    """Catch-all handler for logging."""
+    print(f"📨 Webhook received: {event.type.value}")
+
+
+# Webhook endpoint
+@app.post("/webhooks/payplus")
+async def payplus_webhook(request: Request):
+    """
+    PayPlus IPN/Webhook endpoint.
+    
+    Configure this URL in your PayPlus dashboard:
+    https://your-domain.com/webhooks/payplus
+    """
+    payload = await request.body()
+    signature = request.headers.get("X-PayPlus-Signature", "")
+    
+    try:
+        event = await webhooks.handle_async(payload, signature)
+        return {
+            "received": True,
+            "event_id": event.id,
+            "event_type": event.type.value,
+        }
+    except WebhookSignatureError:
+        raise HTTPException(status_code=400, detail="Invalid signature")
+    except Exception as e:
+        print(f"Webhook error: {e}")
+        raise HTTPException(status_code=500, detail="Webhook processing failed")
+
+
+# Health check
+@app.get("/health")
+async def health():
+    return {"status": "healthy"}
+
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=8000)

examples/subscription_saas.py

@@ -0,0 +1,206 @@
+"""
+Full SaaS subscription example with MongoDB storage.
+"""
+
+import asyncio
+import os
+from decimal import Decimal
+
+from payplus import PayPlus, SubscriptionManager
+from payplus.subscriptions.storage import MongoDBStorage
+from payplus.subscriptions import BillingService
+
+
+async def main():
+    # Initialize PayPlus client
+    client = PayPlus(
+        api_key=os.environ.get("PAYPLUS_API_KEY", "your_api_key"),
+        secret_key=os.environ.get("PAYPLUS_SECRET_KEY", "your_secret_key"),
+        sandbox=True,
+    )
+    
+    # Setup MongoDB storage
+    try:
+        from motor.motor_asyncio import AsyncIOMotorClient
+        mongo = AsyncIOMotorClient(os.environ.get("MONGODB_URI", "mongodb://localhost:27017"))
+        storage = MongoDBStorage(mongo.payplus_demo)
+        await storage.create_indexes()
+    except ImportError:
+        print("MongoDB not available, using in-memory storage")
+        storage = None
+    
+    # Create subscription manager
+    manager = SubscriptionManager(client, storage)
+    
+    # Register event handlers
+    manager.on("subscription.created", lambda s: print(f"✅ Subscription created: {s.id}"))
+    manager.on("subscription.activated", lambda s: print(f"🎉 Subscription activated: {s.id}"))
+    manager.on("payment.succeeded", lambda p: print(f"💰 Payment received: {p.amount} {p.currency}"))
+    manager.on("payment.failed", lambda p: print(f"❌ Payment failed: {p.failure_message}"))
+    
+    # ==================== Setup Pricing Tiers ====================
+    print("\n📦 Creating pricing tiers...")
+    
+    # Free tier
+    free_tier = await manager.create_tier(
+        tier_id="free",
+        name="Free",
+        price=Decimal("0"),
+        features=[
+            {"feature_id": "projects", "name": "Projects", "included_quantity": 3},
+            {"feature_id": "storage_gb", "name": "Storage (GB)", "included_quantity": 1},
+            {"feature_id": "team_members", "name": "Team Members", "included_quantity": 1},
+        ],
+    )
+    print(f"  - {free_tier.name}: ₪{free_tier.price}/month")
+    
+    # Basic tier
+    basic_tier = await manager.create_tier(
+        tier_id="basic",
+        name="Basic",
+        price=Decimal("29"),
+        trial_days=7,
+        features=[
+            {"feature_id": "projects", "name": "Projects", "included_quantity": 10},
+            {"feature_id": "storage_gb", "name": "Storage (GB)", "included_quantity": 10},
+            {"feature_id": "team_members", "name": "Team Members", "included_quantity": 5},
+            {"feature_id": "api_access", "name": "API Access"},
+        ],
+    )
+    print(f"  - {basic_tier.name}: ₪{basic_tier.price}/month (7-day trial)")
+    
+    # Pro tier
+    pro_tier = await manager.create_tier(
+        tier_id="pro",
+        name="Pro",
+        price=Decimal("79"),
+        trial_days=14,
+        is_popular=True,
+        annual_discount_percent=Decimal("20"),
+        features=[
+            {"feature_id": "projects", "name": "Projects", "included_quantity": None},  # Unlimited
+            {"feature_id": "storage_gb", "name": "Storage (GB)", "included_quantity": 100},
+            {"feature_id": "team_members", "name": "Team Members", "included_quantity": 20},
+            {"feature_id": "api_access", "name": "API Access"},
+            {"feature_id": "priority_support", "name": "Priority Support"},
+            {"feature_id": "custom_domain", "name": "Custom Domain"},
+        ],
+    )
+    print(f"  - {pro_tier.name}: ₪{pro_tier.price}/month (14-day trial, 20% annual discount)")
+    
+    # Enterprise tier
+    enterprise_tier = await manager.create_tier(
+        tier_id="enterprise",
+        name="Enterprise",
+        price=Decimal("199"),
+        annual_discount_percent=Decimal("25"),
+        features=[
+            {"feature_id": "projects", "name": "Projects", "included_quantity": None},
+            {"feature_id": "storage_gb", "name": "Storage (GB)", "included_quantity": None},
+            {"feature_id": "team_members", "name": "Team Members", "included_quantity": None},
+            {"feature_id": "api_access", "name": "API Access"},
+            {"feature_id": "priority_support", "name": "Priority Support"},
+            {"feature_id": "custom_domain", "name": "Custom Domain"},
+            {"feature_id": "sso", "name": "SSO Integration"},
+            {"feature_id": "dedicated_support", "name": "Dedicated Account Manager"},
+        ],
+    )
+    print(f"  - {enterprise_tier.name}: ₪{enterprise_tier.price}/month (25% annual discount)")
+    
+    # ==================== Create Customer ====================
+    print("\n👤 Creating customer...")
+    
+    customer = await manager.create_customer(
+        email="demo@example.com",
+        name="Demo User",
+        metadata={"source": "signup_form", "campaign": "launch_2024"},
+    )
+    print(f"  Customer ID: {customer.id}")
+    print(f"  Email: {customer.email}")
+    
+    # ==================== Add Payment Method ====================
+    print("\n💳 Adding payment method...")
+    
+    # In production, this token comes from a PayPlus payment page
+    # For demo, we'll simulate with a fake token
+    demo_token = "demo_card_token_xxx"
+    
+    payment_method = await manager.add_payment_method(
+        customer_id=customer.id,
+        token=demo_token,
+        card_brand="Visa",
+        last_four="4242",
+        expiry_month="12",
+        expiry_year="2028",
+    )
+    print(f"  Payment Method: {payment_method.card_brand} ****{payment_method.last_four}")
+    
+    # ==================== Create Subscription ====================
+    print("\n📋 Creating Pro subscription...")
+    
+    subscription = await manager.create_subscription(
+        customer_id=customer.id,
+        tier_id="pro",
+    )
+    
+    print(f"  Subscription ID: {subscription.id}")
+    print(f"  Status: {subscription.status}")
+    print(f"  Amount: ₪{subscription.amount}/month")
+    print(f"  Trial ends: {subscription.trial_end}")
+    print(f"  Current period: {subscription.current_period_start} - {subscription.current_period_end}")
+    
+    # ==================== Subscription Operations ====================
+    print("\n⚙️ Subscription operations...")
+    
+    # Check if active
+    print(f"  Is active: {subscription.is_active}")
+    print(f"  Is trialing: {subscription.is_trialing}")
+    
+    # Upgrade to enterprise
+    print("\n  📈 Upgrading to Enterprise...")
+    subscription = await manager.change_tier(subscription.id, "enterprise")
+    print(f"  New tier: {subscription.tier_id}")
+    print(f"  New amount: ₪{subscription.amount}/month")
+    
+    # Pause subscription
+    print("\n  ⏸️ Pausing subscription...")
+    subscription = await manager.pause_subscription(subscription.id)
+    print(f"  Status: {subscription.status}")
+    
+    # Resume subscription
+    print("\n  ▶️ Resuming subscription...")
+    subscription = await manager.resume_subscription(subscription.id)
+    print(f"  Status: {subscription.status}")
+    
+    # Cancel at period end
+    print("\n  🚫 Scheduling cancellation...")
+    subscription = await manager.cancel_subscription(
+        subscription.id,
+        at_period_end=True,
+        reason="Demo completed",
+    )
+    print(f"  Will cancel at: {subscription.current_period_end}")
+    print(f"  Cancellation reason: {subscription.cancellation_reason}")
+    
+    # ==================== Billing Service ====================
+    print("\n💵 Billing service...")
+    
+    billing = BillingService(manager)
+    
+    # In production, these would run on a schedule
+    print("  Processing due renewals...")
+    renewed = await billing.process_due_renewals()
+    print(f"  Renewed: {len(renewed)} subscriptions")
+    
+    print("  Processing trial endings...")
+    converted = await billing.process_trial_endings()
+    print(f"  Converted: {len(converted)} trials")
+    
+    print("\n✅ Demo completed!")
+    
+    # Cleanup
+    client.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

payplus/__init__.py

@@ -0,0 +1,30 @@
+"""
+PayPlus Python SDK - Payment gateway integration with subscription management for SaaS apps.
+"""
+
+from payplus.client import PayPlus
+from payplus.subscriptions.manager import SubscriptionManager
+from payplus.models.subscription import (
+    Subscription,
+    SubscriptionStatus,
+    BillingCycle,
+)
+from payplus.models.customer import Customer
+from payplus.models.payment import Payment, PaymentStatus
+from payplus.models.invoice import Invoice, InvoiceStatus
+from payplus.models.tier import Tier
+
+__version__ = "0.1.0"
+__all__ = [
+    "PayPlus",
+    "SubscriptionManager",
+    "Subscription",
+    "SubscriptionStatus",
+    "BillingCycle",
+    "Customer",
+    "Payment",
+    "PaymentStatus",
+    "Invoice",
+    "InvoiceStatus",
+    "Tier",
+]

payplus/api/__init__.py

@@ -0,0 +1,15 @@
+"""
+PayPlus API modules.
+"""
+
+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
+
+__all__ = [
+    "PaymentsAPI",
+    "RecurringAPI",
+    "TransactionsAPI",
+    "PaymentPagesAPI",
+]

payplus/api/base.py

@@ -0,0 +1,37 @@
+"""
+Base API class for PayPlus endpoints.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Optional
+
+if TYPE_CHECKING:
+    from payplus.client import PayPlus
+
+
+class BaseAPI:
+    """Base class for API endpoints."""
+    
+    def __init__(self, client: "PayPlus"):
+        self._client = 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."""
+        return self._client._request(method, endpoint, data, params)
+    
+    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."""
+        return await self._client._async_request(method, endpoint, data, params)

payplus/api/payment_pages.py

@@ -0,0 +1,176 @@
+"""
+PayPlus Payment Pages API.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+from decimal import Decimal
+
+from payplus.api.base import BaseAPI
+
+
+class PaymentPagesAPI(BaseAPI):
+    """
+    Payment Pages API for generating payment links and handling hosted checkout.
+    """
+    
+    def generate_link(
+        self,
+        amount: float | Decimal,
+        currency: str = "ILS",
+        description: Optional[str] = None,
+        customer_uid: Optional[str] = None,
+        customer_email: Optional[str] = None,
+        customer_name: Optional[str] = None,
+        customer_phone: Optional[str] = None,
+        charge_method: int = 1,
+        payments: int = 1,
+        min_payments: int = 1,
+        max_payments: int = 12,
+        success_url: Optional[str] = None,
+        failure_url: Optional[str] = None,
+        cancel_url: Optional[str] = None,
+        callback_url: Optional[str] = None,
+        create_token: bool = False,
+        refurl_address: Optional[str] = None,
+        language: str = "he",
+        expiration_time: int = 60,
+        more_info: Optional[str] = None,
+        more_info_1: Optional[str] = None,
+        more_info_2: Optional[str] = None,
+        items: Optional[list[dict[str, Any]]] = None,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """
+        Generate a payment link for hosted checkout.
+        
+        Args:
+            amount: Payment amount
+            currency: Currency code (default: ILS)
+            description: Payment description
+            customer_uid: Existing customer UID
+            customer_email: Customer email
+            customer_name: Customer name
+            customer_phone: Customer phone
+            charge_method: Charge method (1=regular, 2=recurring, 3=token only)
+            payments: Number of installments
+            min_payments: Minimum installments
+            max_payments: Maximum installments
+            success_url: URL to redirect on success
+            failure_url: URL to redirect on failure
+            cancel_url: URL to redirect on cancel
+            callback_url: IPN/webhook callback URL
+            create_token: Whether to tokenize the card
+            refurl_address: Refund URL
+            language: Page language (he/en)
+            expiration_time: Link expiration in minutes
+            more_info: Custom field 1
+            more_info_1: Custom field 2
+            more_info_2: Custom field 3
+            items: List of items with name, price, quantity
+            
+        Returns:
+            API response with payment link URL
+        """
+        data: dict[str, Any] = {
+            "payment_page_uid": kwargs.get("payment_page_uid"),
+            "charge_method": charge_method,
+            "amount": float(amount),
+            "currency_code": currency,
+            "sendEmailApproval": kwargs.get("send_email_approval", True),
+            "sendEmailFailure": kwargs.get("send_email_failure", False),
+            "create_token": create_token,
+            "payments": payments,
+            "min_payments": min_payments,
+            "max_payments": max_payments,
+            "language_code": language,
+            "expiry_datetime": expiration_time,
+        }
+        
+        if description:
+            data["more_info"] = description
+        if more_info:
+            data["more_info"] = more_info
+        if more_info_1:
+            data["more_info_1"] = more_info_1
+        if more_info_2:
+            data["more_info_2"] = more_info_2
+        
+        # Customer info
+        customer = {}
+        if customer_uid:
+            customer["customer_uid"] = customer_uid
+        if customer_email:
+            customer["email"] = customer_email
+        if customer_name:
+            customer["customer_name"] = customer_name
+        if customer_phone:
+            customer["phone"] = customer_phone
+        if customer:
+            data["customer"] = customer
+        
+        # URLs
+        if success_url:
+            data["success_page_url"] = success_url
+        if failure_url:
+            data["failure_page_url"] = failure_url
+        if cancel_url:
+            data["cancel_page_url"] = cancel_url
+        if callback_url:
+            data["callback_url"] = callback_url
+        if refurl_address:
+            data["refurl_address"] = refurl_address
+        
+        # Items
+        if items:
+            data["items"] = items
+        
+        # Add terminal if set
+        if self._client.terminal_uid:
+            data["terminal_uid"] = self._client.terminal_uid
+        
+        # Add any extra kwargs
+        for key, value in kwargs.items():
+            if key not in data and value is not None:
+                data[key] = value
+        
+        return self._request("POST", "PaymentPages/generateLink", data)
+    
+    async def async_generate_link(
+        self,
+        amount: float | Decimal,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """Async version of generate_link."""
+        # Build data same as sync version
+        data: dict[str, Any] = {
+            "charge_method": kwargs.get("charge_method", 1),
+            "amount": float(amount),
+            "currency_code": kwargs.get("currency", "ILS"),
+            "sendEmailApproval": kwargs.get("send_email_approval", True),
+            "sendEmailFailure": kwargs.get("send_email_failure", False),
+            "create_token": kwargs.get("create_token", False),
+            "payments": kwargs.get("payments", 1),
+            "language_code": kwargs.get("language", "he"),
+        }
+        
+        if kwargs.get("description"):
+            data["more_info"] = kwargs["description"]
+        
+        if self._client.terminal_uid:
+            data["terminal_uid"] = self._client.terminal_uid
+        
+        return await self._async_request("POST", "PaymentPages/generateLink", data)
+    
+    def get_status(self, page_request_uid: str) -> dict[str, Any]:
+        """
+        Get payment page status.
+        
+        Args:
+            page_request_uid: Payment page request UID
+            
+        Returns:
+            Payment page status
+        """
+        return self._request("GET", f"PaymentPages/{page_request_uid}")