python-getpaid-core 0.1.0__py3-none-any.whl

getpaid_core/__init__.py

@@ -0,0 +1,39 @@
+"""Getpaid Core -- framework-agnostic payment processing."""
+
+__version__ = "0.1.0"
+
+from getpaid_core.enums import BackendMethod
+from getpaid_core.enums import ConfirmationMethod
+from getpaid_core.enums import FraudStatus
+from getpaid_core.enums import PaymentStatus
+from getpaid_core.exceptions import ChargeFailure
+from getpaid_core.exceptions import CommunicationError
+from getpaid_core.exceptions import CredentialsError
+from getpaid_core.exceptions import GetPaidException
+from getpaid_core.exceptions import InvalidCallbackError
+from getpaid_core.exceptions import InvalidTransitionError
+from getpaid_core.exceptions import LockFailure
+from getpaid_core.exceptions import RefundFailure
+from getpaid_core.flow import PaymentFlow
+from getpaid_core.processor import BaseProcessor
+from getpaid_core.registry import registry
+
+
+__all__ = [
+    "BackendMethod",
+    "BaseProcessor",
+    "ChargeFailure",
+    "CommunicationError",
+    "ConfirmationMethod",
+    "CredentialsError",
+    "FraudStatus",
+    "GetPaidException",
+    "InvalidCallbackError",
+    "InvalidTransitionError",
+    "LockFailure",
+    "PaymentFlow",
+    "PaymentStatus",
+    "RefundFailure",
+    "__version__",
+    "registry",
+]

getpaid_core/backends/__init__.py

@@ -0,0 +1 @@
+"""Built-in payment backends."""

getpaid_core/backends/dummy.py

@@ -0,0 +1,95 @@
+"""Dummy payment backend for development and testing.
+
+Makes zero HTTP calls. Serves as a reference implementation
+for backend authors.
+"""
+
+from decimal import Decimal
+from typing import ClassVar
+
+from getpaid_core.fsm import ALLOWED_CALLBACKS
+from getpaid_core.processor import BaseProcessor
+from getpaid_core.types import ChargeResponse
+from getpaid_core.types import PaymentStatusResponse
+from getpaid_core.types import TransactionResult
+
+
+class DummyProcessor(BaseProcessor):
+    """Dummy processor that simulates all payment operations."""
+
+    slug: ClassVar[str] = "dummy"
+    display_name: ClassVar[str] = "Dummy"
+    accepted_currencies: ClassVar[list[str]] = [
+        "PLN",
+        "EUR",
+        "USD",
+        "GBP",
+        "CHF",
+        "CZK",
+    ]
+
+    async def prepare_transaction(self, **kwargs) -> TransactionResult:
+        method = self.get_setting("method", "REST")
+        if method == "POST":
+            return TransactionResult(
+                redirect_url="https://dummy.example.com/form",
+                form_data={
+                    "payment_id": self.payment.id,
+                    "amount": str(self.payment.amount_required),
+                    "currency": self.payment.currency,
+                },
+                method="POST",
+                headers={},
+            )
+        elif method == "GET":
+            return TransactionResult(
+                redirect_url=(
+                    f"https://dummy.example.com/pay/{self.payment.id}"
+                ),
+                form_data=None,
+                method="GET",
+                headers={},
+            )
+        else:
+            return TransactionResult(
+                redirect_url=(
+                    f"https://dummy.example.com/pay/{self.payment.id}"
+                ),
+                form_data=None,
+                method="REST",
+                headers={},
+            )
+
+    async def handle_callback(
+        self, data: dict, headers: dict, **kwargs
+    ) -> None:
+        new_status = data.get("new_status")
+        if new_status and new_status in ALLOWED_CALLBACKS:
+            trigger = getattr(self.payment, new_status, None)
+            if trigger and callable(trigger):
+                trigger()
+
+    async def fetch_payment_status(self, **kwargs) -> PaymentStatusResponse:
+        status = self.get_setting("confirmation_status", "confirm_payment")
+        return PaymentStatusResponse(status=status)
+
+    async def charge(
+        self, amount: Decimal | None = None, **kwargs
+    ) -> ChargeResponse:
+        charged = amount if amount is not None else self.payment.amount_required
+        return ChargeResponse(
+            amount_charged=charged,
+            success=True,
+            async_call=False,
+        )
+
+    async def release_lock(self, **kwargs) -> Decimal:
+        return self.payment.amount_locked
+
+    async def start_refund(
+        self, amount: Decimal | None = None, **kwargs
+    ) -> Decimal:
+        return amount if amount is not None else self.payment.amount_paid
+
+    async def cancel_refund(self, **kwargs) -> bool:
+        return True

getpaid_core/enums.py

@@ -0,0 +1,44 @@
+"""Payment processing enums.
+
+Values are kept identical to django-getpaid for backward compatibility.
+"""
+
+from enum import StrEnum
+
+
+class PaymentStatus(StrEnum):
+    """Internal payment status."""
+
+    NEW = "new"
+    PREPARED = "prepared"
+    PRE_AUTH = "pre-auth"
+    IN_CHARGE = "charge_started"
+    PARTIAL = "partially_paid"
+    PAID = "paid"
+    FAILED = "failed"
+    REFUND_STARTED = "refund_started"
+    REFUNDED = "refunded"
+
+
+class FraudStatus(StrEnum):
+    """Fraud verification status."""
+
+    UNKNOWN = "unknown"
+    ACCEPTED = "accepted"
+    REJECTED = "rejected"
+    CHECK = "check"
+
+
+class BackendMethod(StrEnum):
+    """HTTP method used to initiate payment."""
+
+    GET = "GET"
+    POST = "POST"
+    REST = "REST"
+
+
+class ConfirmationMethod(StrEnum):
+    """How the payment gateway confirms payment status."""
+
+    PUSH = "PUSH"
+    PULL = "PULL"

getpaid_core/exceptions.py

@@ -0,0 +1,37 @@
+"""Exception hierarchy for payment processing."""
+
+
+class GetPaidException(Exception):
+    """Base exception for all getpaid errors."""
+
+    def __init__(self, message: str = "", context: dict | None = None) -> None:
+        super().__init__(message)
+        self.context = context or {}
+
+
+class CommunicationError(GetPaidException):
+    """Error communicating with payment gateway."""
+
+
+class ChargeFailure(CommunicationError):
+    """Failed to charge payment."""
+
+
+class LockFailure(CommunicationError):
+    """Failed to lock (pre-authorize) payment."""
+
+
+class RefundFailure(CommunicationError):
+    """Failed to process refund."""
+
+
+class CredentialsError(GetPaidException):
+    """Invalid or missing gateway credentials."""
+
+
+class InvalidCallbackError(GetPaidException):
+    """Callback verification failed."""
+
+
+class InvalidTransitionError(GetPaidException):
+    """Attempted invalid state transition."""

getpaid_core/flow.py

@@ -0,0 +1,140 @@
+"""Payment flow orchestrator.
+
+The main entry point for framework adapters. Orchestrates the
+interaction between repository, processor, and state machine.
+"""
+
+from getpaid_core.exceptions import InvalidTransitionError
+from getpaid_core.fsm import ALLOWED_CALLBACKS
+from getpaid_core.fsm import create_fraud_machine
+from getpaid_core.fsm import create_payment_machine
+from getpaid_core.protocols import Order
+from getpaid_core.protocols import Payment
+from getpaid_core.protocols import PaymentRepository
+from getpaid_core.registry import registry
+from getpaid_core.types import TransactionResult
+from getpaid_core.validators import run_validators
+
+
+class PaymentFlow:
+    """Core payment processing orchestrator.
+
+    Framework adapters create an instance with their repository
+    and backend configuration, then delegate to its methods.
+    """
+
+    def __init__(
+        self,
+        repository: PaymentRepository,
+        config: dict | None = None,
+        validators: list | None = None,
+    ) -> None:
+        self.repository = repository
+        self.config = config or {}
+        self.validators = validators or []
+
+    async def create_payment(
+        self, order: Order, backend_slug: str, **kwargs
+    ) -> Payment:
+        """Create a new payment for an order."""
+        registry.get_by_slug(backend_slug)
+        payment = await self.repository.create(
+            order=order,
+            backend=backend_slug,
+            amount_required=order.get_total_amount(),
+            currency=order.get_currency(),
+            description=order.get_description(),
+            **kwargs,
+        )
+        return payment
+
+    async def prepare(self, payment: Payment, **kwargs) -> TransactionResult:
+        """Prepare a payment for processing.
+
+        Runs validators, calls the backend's prepare_transaction(),
+        transitions to PREPARED, and persists.
+        """
+        run_validators({"payment": payment}, validators=self.validators)
+        create_payment_machine(payment)
+        processor = self._get_processor(payment)
+        result = await processor.prepare_transaction(**kwargs)
+        payment.confirm_prepared()
+        await self.repository.save(payment)
+        return result
+
+    async def handle_callback(
+        self,
+        payment: Payment,
+        data: dict,
+        headers: dict,
+        **kwargs,
+    ) -> None:
+        """Handle an incoming PUSH callback from the gateway."""
+        processor = self._get_processor(payment)
+        await processor.verify_callback(data, headers, **kwargs)
+        create_payment_machine(payment)
+        create_fraud_machine(payment)
+        await processor.handle_callback(data, headers, **kwargs)
+        await self.repository.save(payment)
+
+    async def fetch_and_update_status(self, payment: Payment) -> Payment:
+        """PULL flow: fetch status from gateway and update."""
+        processor = self._get_processor(payment)
+        create_payment_machine(payment)
+        create_fraud_machine(payment)
+        response = await processor.fetch_payment_status()
+        if response.get("status"):
+            callback = response["status"]
+            if callback not in ALLOWED_CALLBACKS:
+                raise InvalidTransitionError(
+                    f"Callback {callback!r} not in ALLOWED_CALLBACKS"
+                )
+            trigger = getattr(payment, callback, None)
+            if trigger and callable(trigger):
+                trigger()
+        await self.repository.save(payment)
+        return payment
+
+    async def charge(self, payment: Payment, amount=None, **kwargs):
+        """Charge a pre-authorized payment."""
+        processor = self._get_processor(payment)
+        create_payment_machine(payment)
+        result = await processor.charge(amount=amount, **kwargs)
+        if result["success"]:
+            payment.confirm_charge_sent()
+        await self.repository.save(payment)
+        return result
+
+    async def release_lock(self, payment: Payment, **kwargs):
+        """Release a pre-authorized lock."""
+        processor = self._get_processor(payment)
+        create_payment_machine(payment)
+        amount = await processor.release_lock(**kwargs)
+        payment.release_lock()
+        await self.repository.save(payment)
+        return amount
+
+    async def start_refund(self, payment: Payment, amount=None, **kwargs):
+        """Start a refund."""
+        processor = self._get_processor(payment)
+        create_payment_machine(payment)
+        refund_amount = await processor.start_refund(amount=amount, **kwargs)
+        payment.start_refund()
+        await self.repository.save(payment)
+        return refund_amount
+
+    async def cancel_refund(self, payment: Payment, **kwargs):
+        """Cancel an in-progress refund."""
+        processor = self._get_processor(payment)
+        create_payment_machine(payment)
+        success = await processor.cancel_refund(**kwargs)
+        if success:
+            payment.cancel_refund()
+            await self.repository.save(payment)
+        return success
+
+    def _get_processor(self, payment: Payment):
+        """Instantiate the processor for a payment."""
+        processor_class = registry.get_by_slug(payment.backend)
+        backend_config = self.config.get(payment.backend, {})
+        return processor_class(payment, config=backend_config)

getpaid_core/fsm.py

@@ -0,0 +1,205 @@
+"""Payment state machine using the transitions library.
+
+Defines all valid payment and fraud status transitions.
+The machine attaches trigger methods directly to payment objects.
+"""
+
+from transitions import Machine
+from transitions.core import MachineError
+
+from getpaid_core.enums import FraudStatus
+from getpaid_core.enums import PaymentStatus
+
+
+def _require_fully_paid(event_data):
+    """Guard that raises MachineError when payment is not fully paid."""
+    model = event_data.model
+    if not model.is_fully_paid():
+        raise MachineError(
+            f"Transition '{event_data.event.name}' requires full payment."
+        )
+
+
+def _require_fully_refunded(event_data):
+    """Guard that raises MachineError when payment is not fully refunded."""
+    model = event_data.model
+    if not model.is_fully_refunded():
+        raise MachineError(
+            f"Transition '{event_data.event.name}' requires full refund."
+        )
+
+
+def _store_locked_amount(event_data):
+    """After confirm_lock: store the locked amount on the payment."""
+    model = event_data.model
+    amount = event_data.kwargs.get("amount", None)
+    if amount is None:
+        amount = model.amount_required
+    model.amount_locked = amount
+
+
+def _accumulate_paid_amount(event_data):
+    """After confirm_payment: accumulate paid amount on the payment."""
+    model = event_data.model
+    amount = event_data.kwargs.get("amount", None)
+    if amount is None:
+        if not model.amount_locked:
+            model.amount_locked = model.amount_required
+        amount = model.amount_locked
+    model.amount_paid += amount
+
+
+PAYMENT_TRANSITIONS = [
+    {
+        "trigger": "confirm_prepared",
+        "source": PaymentStatus.NEW,
+        "dest": PaymentStatus.PREPARED,
+    },
+    {
+        "trigger": "confirm_lock",
+        "source": [PaymentStatus.NEW, PaymentStatus.PREPARED],
+        "dest": PaymentStatus.PRE_AUTH,
+        "after": _store_locked_amount,
+    },
+    {
+        "trigger": "confirm_charge_sent",
+        "source": PaymentStatus.PRE_AUTH,
+        "dest": PaymentStatus.IN_CHARGE,
+    },
+    {
+        "trigger": "confirm_payment",
+        "source": [
+            PaymentStatus.PRE_AUTH,
+            PaymentStatus.PREPARED,
+            PaymentStatus.IN_CHARGE,
+            PaymentStatus.PARTIAL,
+        ],
+        "dest": PaymentStatus.PARTIAL,
+        "after": _accumulate_paid_amount,
+    },
+    {
+        "trigger": "mark_as_paid",
+        "source": PaymentStatus.PARTIAL,
+        "dest": PaymentStatus.PAID,
+        "before": _require_fully_paid,
+    },
+    {
+        "trigger": "release_lock",
+        "source": PaymentStatus.PRE_AUTH,
+        "dest": PaymentStatus.REFUNDED,
+    },
+    {
+        "trigger": "start_refund",
+        "source": [
+            PaymentStatus.PAID,
+            PaymentStatus.PARTIAL,
+        ],
+        "dest": PaymentStatus.REFUND_STARTED,
+    },
+    {
+        "trigger": "cancel_refund",
+        "source": PaymentStatus.REFUND_STARTED,
+        "dest": PaymentStatus.PARTIAL,
+    },
+    {
+        "trigger": "confirm_refund",
+        "source": PaymentStatus.REFUND_STARTED,
+        "dest": PaymentStatus.PARTIAL,
+    },
+    {
+        "trigger": "mark_as_refunded",
+        "source": PaymentStatus.PARTIAL,
+        "dest": PaymentStatus.REFUNDED,
+        "before": _require_fully_refunded,
+    },
+    {
+        "trigger": "fail",
+        "source": [
+            PaymentStatus.NEW,
+            PaymentStatus.PRE_AUTH,
+            PaymentStatus.PREPARED,
+        ],
+        "dest": PaymentStatus.FAILED,
+    },
+]
+
+FRAUD_TRANSITIONS = [
+    {
+        "trigger": "flag_as_fraud",
+        "source": FraudStatus.UNKNOWN,
+        "dest": FraudStatus.REJECTED,
+    },
+    {
+        "trigger": "flag_as_legit",
+        "source": FraudStatus.UNKNOWN,
+        "dest": FraudStatus.ACCEPTED,
+    },
+    {
+        "trigger": "flag_for_check",
+        "source": FraudStatus.UNKNOWN,
+        "dest": FraudStatus.CHECK,
+    },
+    {
+        "trigger": "mark_as_fraud",
+        "source": FraudStatus.CHECK,
+        "dest": FraudStatus.REJECTED,
+    },
+    {
+        "trigger": "mark_as_legit",
+        "source": FraudStatus.CHECK,
+        "dest": FraudStatus.ACCEPTED,
+    },
+]
+
+ALLOWED_CALLBACKS: frozenset[str] = frozenset(
+    {
+        "confirm_prepared",
+        "confirm_lock",
+        "confirm_charge_sent",
+        "confirm_payment",
+        "mark_as_paid",
+        "release_lock",
+        "start_refund",
+        "cancel_refund",
+        "confirm_refund",
+        "mark_as_refunded",
+        "fail",
+    }
+)
+
+
+def create_payment_machine(payment) -> Machine:
+    """Attach payment FSM to a payment object.
+
+    The transitions library adds trigger methods directly to the
+    object (confirm_prepared, confirm_lock, fail, etc.).
+    """
+    return Machine(
+        model=payment,
+        states=PaymentStatus,
+        transitions=PAYMENT_TRANSITIONS,
+        initial=payment.status or PaymentStatus.NEW,
+        model_attribute="status",
+        auto_transitions=False,
+        send_event=True,
+    )
+
+
+def _store_fraud_message(event):
+    """Before callback: store message kwarg on the payment object."""
+    message = event.kwargs.get("message", "")
+    event.model.fraud_message = message
+
+
+def create_fraud_machine(payment) -> Machine:
+    """Attach fraud status FSM to a payment object."""
+    return Machine(
+        model=payment,
+        states=FraudStatus,
+        transitions=FRAUD_TRANSITIONS,
+        initial=payment.fraud_status or FraudStatus.UNKNOWN,
+        model_attribute="fraud_status",
+        auto_transitions=False,
+        send_event=True,
+        before_state_change=[_store_fraud_message],
+    )

getpaid_core/processor.py

@@ -0,0 +1,87 @@
+"""Base payment processor abstract class.
+
+All payment backends subclass BaseProcessor and implement at minimum
+prepare_transaction(). Other methods are optional depending on the
+payment gateway's capabilities.
+"""
+
+from abc import ABC
+from abc import abstractmethod
+from decimal import Decimal
+from typing import ClassVar
+
+from getpaid_core.protocols import Payment
+from getpaid_core.types import ChargeResponse
+from getpaid_core.types import PaymentStatusResponse
+from getpaid_core.types import TransactionResult
+
+
+class BaseProcessor(ABC):
+    """Base class for payment backend processors."""
+
+    slug: ClassVar[str] = ""
+    display_name: ClassVar[str] = ""
+    accepted_currencies: ClassVar[list[str]] = []
+    logo_url: ClassVar[str | None] = None
+    sandbox_url: ClassVar[str] = ""
+    production_url: ClassVar[str] = ""
+
+    def __init__(self, payment: Payment, config: dict | None = None) -> None:
+        self.payment = payment
+        self.config = config or {}
+
+    def get_setting(self, name: str, default=None):
+        """Read a setting from backend config."""
+        return self.config.get(name, default)
+
+    def get_paywall_baseurl(self) -> str:
+        """Return sandbox or production URL based on config."""
+        sandbox = self.get_setting("sandbox", True)
+        return self.sandbox_url if sandbox else self.production_url
+
+    @abstractmethod
+    async def prepare_transaction(self, **kwargs) -> TransactionResult:
+        """Prepare data for initiating a payment.
+
+        Returns a TransactionResult that the framework adapter
+        converts into an HTTP response.
+        """
+        ...
+
+    async def verify_callback(
+        self, data: dict, headers: dict, **kwargs
+    ) -> None:
+        """Verify callback authenticity.
+
+        Raise GetPaidException to reject. Default: no-op.
+        """
+
+    async def handle_callback(
+        self, data: dict, headers: dict, **kwargs
+    ) -> None:
+        """Handle async PUSH callback from payment gateway."""
+        raise NotImplementedError
+
+    async def fetch_payment_status(self, **kwargs) -> PaymentStatusResponse:
+        """PULL flow: fetch payment status from gateway."""
+        raise NotImplementedError
+
+    async def charge(
+        self, amount: Decimal | None = None, **kwargs
+    ) -> ChargeResponse:
+        """Charge a pre-authorized payment."""
+        raise NotImplementedError
+
+    async def release_lock(self, **kwargs) -> Decimal:
+        """Release pre-authorized lock. Return locked amount."""
+        raise NotImplementedError
+
+    async def start_refund(
+        self, amount: Decimal | None = None, **kwargs
+    ) -> Decimal:
+        """Start a refund. Return refund amount."""
+        raise NotImplementedError
+
+    async def cancel_refund(self, **kwargs) -> bool:
+        """Cancel in-progress refund. Return True if ok."""
+        raise NotImplementedError

getpaid_core/protocols.py

@@ -0,0 +1,57 @@
+"""Protocols defining framework integration contracts.
+
+Framework adapters (django-getpaid, litestar-getpaid, etc.) provide
+concrete implementations. Any object with the right shape satisfies
+the protocol -- no inheritance required.
+"""
+
+from decimal import Decimal
+from typing import Protocol
+from typing import runtime_checkable
+
+from getpaid_core.types import BuyerInfo
+from getpaid_core.types import ItemInfo
+
+
+@runtime_checkable
+class Order(Protocol):
+    """What the core expects from an order object."""
+
+    def get_total_amount(self) -> Decimal: ...
+    def get_buyer_info(self) -> BuyerInfo: ...
+    def get_description(self) -> str: ...
+    def get_currency(self) -> str: ...
+    def get_items(self) -> list[ItemInfo]: ...
+    def get_return_url(self, success: bool | None = None) -> str: ...
+
+
+@runtime_checkable
+class Payment(Protocol):
+    """What the core expects from a payment object."""
+
+    id: str
+    order: Order
+    amount_required: Decimal
+    currency: str
+    status: str
+    backend: str
+    external_id: str
+    description: str
+    amount_paid: Decimal
+    amount_locked: Decimal
+    amount_refunded: Decimal
+    fraud_status: str
+    fraud_message: str
+
+
+@runtime_checkable
+class PaymentRepository(Protocol):
+    """Persistence abstraction. Framework adapters implement this."""
+
+    async def get_by_id(self, payment_id: str) -> Payment: ...
+    async def create(self, **kwargs) -> Payment: ...
+    async def save(self, payment: Payment) -> Payment: ...
+    async def update_status(
+        self, payment_id: str, status: str, **fields
+    ) -> Payment: ...
+    async def list_by_order(self, order_id: str) -> list[Payment]: ...

getpaid_core/registry.py

@@ -0,0 +1,74 @@
+"""Plugin registry for payment backends.
+
+Primary discovery via entry_points. Manual registration for
+testing and dynamic scenarios.
+"""
+
+from importlib.metadata import entry_points
+
+from getpaid_core.processor import BaseProcessor
+
+
+ENTRY_POINT_GROUP = "getpaid.backends"
+
+
+class PluginRegistry:
+    """Discovers and stores payment backend processors."""
+
+    def __init__(self) -> None:
+        self._backends: dict[str, type[BaseProcessor]] = {}
+        self._discovered = False
+
+    def discover(self) -> None:
+        """Load all backends registered via entry_points."""
+        eps = entry_points(group=ENTRY_POINT_GROUP)
+        for ep in eps:
+            processor_class = ep.load()
+            if isinstance(processor_class, type) and issubclass(
+                processor_class, BaseProcessor
+            ):
+                self._backends[processor_class.slug] = processor_class
+        self._discovered = True
+
+    def register(self, processor_class: type[BaseProcessor]) -> None:
+        """Manual registration for testing or dynamic use."""
+        self._backends[processor_class.slug] = processor_class
+
+    def unregister(self, slug: str) -> None:
+        """Remove a backend by slug."""
+        self._backends.pop(slug, None)
+
+    def get_for_currency(self, currency: str) -> list[type[BaseProcessor]]:
+        """Return all backends supporting the given currency."""
+        self._ensure_discovered()
+        return [
+            b
+            for b in self._backends.values()
+            if currency in b.accepted_currencies
+        ]
+
+    def get_choices(self, currency: str) -> list[tuple[str, str]]:
+        """Return (slug, display_name) pairs for a currency."""
+        return [
+            (b.slug, b.display_name) for b in self.get_for_currency(currency)
+        ]
+
+    def get_by_slug(self, slug: str) -> type[BaseProcessor]:
+        """Return a backend class by slug. Raises KeyError."""
+        self._ensure_discovered()
+        return self._backends[slug]
+
+    def get_all_currencies(self) -> set[str]:
+        """Return all currencies supported by all backends."""
+        self._ensure_discovered()
+        currencies: set[str] = set()
+        for b in self._backends.values():
+            currencies.update(b.accepted_currencies)
+        return currencies
+
+    def _ensure_discovered(self) -> None:
+        if not self._discovered:
+            self.discover()
+
+
+registry = PluginRegistry()

getpaid_core/types.py

@@ -0,0 +1,52 @@
+"""Core type definitions for payment processing."""
+
+from decimal import Decimal
+from typing import TypedDict
+
+
+class BuyerInfo(TypedDict, total=False):
+    """Buyer/customer information."""
+
+    email: str
+    first_name: str
+    last_name: str
+    phone: str
+
+
+class ItemInfo(TypedDict):
+    """Single item in an order."""
+
+    name: str
+    quantity: int
+    unit_price: Decimal
+
+
+class ChargeResponse(TypedDict):
+    """Response from charging a pre-authorized payment."""
+
+    amount_charged: Decimal
+    success: bool
+    async_call: bool
+
+
+class PaymentStatusResponse(TypedDict, total=False):
+    """Response from fetching payment status from gateway."""
+
+    amount: Decimal | None
+    status: str | None
+    external_id: str | None
+
+
+class TransactionResult(TypedDict):
+    """Result of preparing a transaction.
+
+    Framework adapters convert this into framework-specific responses:
+    - GET: redirect to redirect_url
+    - POST: render form that auto-submits to redirect_url with form_data
+    - REST: return JSON or handle internally
+    """
+
+    redirect_url: str | None
+    form_data: dict | None
+    method: str  # 'GET', 'POST', or 'REST'
+    headers: dict[str, str]

getpaid_core/validators.py

@@ -0,0 +1,21 @@
+"""Pluggable payment validation system.
+
+Validators are callables that receive a data dict, optionally
+modify it, and return it. They raise GetPaidException to reject.
+"""
+
+from collections.abc import Callable
+
+
+def run_validators(
+    data: dict,
+    validators: list[Callable] | None = None,
+) -> dict:
+    """Run a chain of validators on payment data.
+
+    Each validator receives the data dict and must return it
+    (possibly modified). Raise GetPaidException to reject.
+    """
+    for validator in validators or []:
+        data = validator(data)
+    return data

python_getpaid_core-0.1.0.dist-info/METADATA

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: python-getpaid-core
+Version: 0.1.0
+Summary: Framework-agnostic payment processing core.
+Project-URL: Homepage, https://github.com/django-getpaid/python-getpaid-core
+Project-URL: Repository, https://github.com/django-getpaid/python-getpaid-core
+Project-URL: Documentation, https://getpaid-core.readthedocs.io
+Project-URL: Changelog, https://github.com/django-getpaid/python-getpaid-core/releases
+Author-email: Dominik Kozaczko <dominik@kozaczko.info>
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Office/Business :: Financial :: Point-Of-Sale
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: anyio>=4.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: transitions>=0.9.0
+Description-Content-Type: text/markdown
+
+# getpaid-core
+
+[![PyPI](https://img.shields.io/pypi/v/python-getpaid-core.svg)](https://pypi.org/project/python-getpaid-core/)
+[![Python Version](https://img.shields.io/pypi/pyversions/python-getpaid-core)](https://pypi.org/project/python-getpaid-core/)
+[![License](https://img.shields.io/pypi/l/python-getpaid-core)](https://github.com/django-getpaid/python-getpaid-core/blob/main/LICENSE)
+
+Framework-agnostic payment processing library for Python. Provides the core
+abstractions — enums, protocols, FSM, processor base class, plugin registry,
+and exception hierarchy — that framework-specific adapters build on.
+
+## Architecture
+
+getpaid-core defines the **what** of payment processing without coupling to
+any web framework:
+
+- **Enums** (`PaymentStatus`, `FraudStatus`, `BackendMethod`, `ConfirmationMethod`)
+  define all valid states and methods.
+- **Protocols** (`Payment`, `Order`, `PaymentRepository`) define structural
+  contracts that framework models must satisfy.
+- **FSM** (`create_payment_machine`, `create_fraud_machine`) attaches
+  state-machine triggers to payment objects at runtime using the `transitions`
+  library.
+- **BaseProcessor** is an abstract class that payment gateway plugins subclass
+  to implement `prepare_transaction`, `handle_callback`, `charge`, etc.
+- **PluginRegistry** discovers and stores payment backend processors via
+  entry points or manual registration.
+- **Exceptions** provide a structured hierarchy for payment errors.
+
+## Framework Adapters
+
+- **[django-getpaid](https://github.com/django-getpaid/django-getpaid)** —
+  Django adapter (models, views, forms, admin)
+
+## Installation
+
+```bash
+pip install python-getpaid-core
+```
+
+You typically install this as a dependency of a framework adapter rather than
+directly.
+
+## Quick Example
+
+```python
+from getpaid_core.enums import PaymentStatus
+from getpaid_core.fsm import create_payment_machine
+
+# Any object satisfying the Payment protocol works
+payment = MyPayment(status=PaymentStatus.NEW, amount_required=100)
+machine = create_payment_machine(payment)
+
+# FSM trigger methods are attached directly to the object
+payment.confirm_prepared()
+assert payment.status == PaymentStatus.PREPARED
+```
+
+## Requirements
+
+- Python 3.12+
+- transitions
+- httpx
+- anyio
+
+## License
+
+MIT
+
+## Disclaimer
+
+This project has nothing in common with the
+[getpaid](http://code.google.com/p/getpaid/) plone project.
+
+## Credits
+
+Created by [Dominik Kozaczko](https://github.com/dekoza).

python_getpaid_core-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+getpaid_core/__init__.py,sha256=soSScP8r9yiOz7kv3dO4uS3x6AX8TnIxul_RzkULUSg,1198
+getpaid_core/enums.py,sha256=arfIwqyHDBRXLb_DbLVQMJvMALG5dkN26KGR1w6G5Wg,866
+getpaid_core/exceptions.py,sha256=XJtXvUdH_mNTP66okUvfvJfY13UURVW0_WPXapbjG9c,913
+getpaid_core/flow.py,sha256=IBgMGArjWxUGjW9mZAIA0pl1IqV_EPkLfy3JxluHiTQ,5312
+getpaid_core/fsm.py,sha256=nxAECNyVthxopNjwenbkbMA7wa7bUnS9o_0od3r0gGU,5637
+getpaid_core/processor.py,sha256=5p1AFObhaF9EO5GWt9KNti9Oxq9whMr68-vSsQf8v6A,2870
+getpaid_core/protocols.py,sha256=CnvgEx5P8u3kYuSDKo_XuQm8hG2ze0Us31KZDn5V8G8,1660
+getpaid_core/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+getpaid_core/registry.py,sha256=1VMncWbZuK3blrzxLygwWi2YSP67WOYs0X5CAa2r4Pg,2421
+getpaid_core/types.py,sha256=Ougk4LBCvlVPkFWJfp0E3rE1hhv7DPKDFnuulfg3shE,1183
+getpaid_core/validators.py,sha256=TLOvMUG51spEVhm4uvSjismpzOesOjljLmd6VWghuWU,570
+getpaid_core/backends/__init__.py,sha256=7xPzfO9dlCcB8I6ZGW9dk24xYxvSrQMe7WTWdu5Phg0,33
+getpaid_core/backends/dummy.py,sha256=-A4yCP3yZM_ctijoZYaM01MmaRgE_itAReVMZnMqxPQ,3088
+python_getpaid_core-0.1.0.dist-info/METADATA,sha256=4nyRd1AjfDgpjEz0QRqrRjiSJx7eSSkhWEqrwfDDOyY,3621
+python_getpaid_core-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+python_getpaid_core-0.1.0.dist-info/licenses/LICENSE,sha256=Nds7k4ZmahVulUUqzk6BZ3Lib61U75QHrBzWXqAhjZQ,1072
+python_getpaid_core-0.1.0.dist-info/RECORD,,

python_getpaid_core-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

python_getpaid_core-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright © 2022 Dominik Kozaczko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.