python-getpaid-core 0.1.1__tar.gz → 3.0.0a3__tar.gz

python_getpaid_core-3.0.0a3/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        run: pip install uv
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Lint with ruff
+        run: uv run ruff check .
+
+      - name: Run tests
+        run: uv run pytest --tb=short

{python_getpaid_core-0.1.1 → python_getpaid_core-3.0.0a3}/.gitignore

@@ -9,3 +9,4 @@
 /src/*.egg-info/
 __pycache__/
 /.idea/
+/uv.lock

python_getpaid_core-3.0.0a3/.sisyphus/evidence/task-22-readme-core.txt

@@ -0,0 +1,7 @@
+README.md verification results:
+Line count: 82
+pip install count: 1
+BaseProcessor count: 5
+Wrappers count: 8
+
+All verification checks PASSED.

python_getpaid_core-3.0.0a3/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: python-getpaid-core
+Version: 3.0.0a3
+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.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.12
+Requires-Dist: anyio>=4.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: transitions>=0.9.0
+Description-Content-Type: text/markdown
+
+# python-getpaid-core
+
+[![PyPI version](https://img.shields.io/pypi/v/python-getpaid-core)](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 core.**
+
+`python-getpaid-core` is the foundation of the Getpaid ecosystem. It provides the abstract interfaces, semantic payment update engine, and plugin registry needed to build a robust payment system without coupling your logic to a specific web framework or payment provider.
+
+## Installation
+
+```bash
+pip install python-getpaid-core
+```
+
+## Quick Start: Creating a Custom Processor
+
+To implement a new payment backend, subclass `BaseProcessor` and implement at least `prepare_transaction`.
+
+```python
+from getpaid_core import BaseProcessor
+from getpaid_core.types import TransactionResult
+
+class MyPaymentProcessor(BaseProcessor):
+    slug = "my-provider"
+    display_name = "My Payment Provider"
+    accepted_currencies = ["USD", "EUR"]
+
+    async def prepare_transaction(self, **kwargs) -> TransactionResult:
+        # Generate payment link or form data
+        return TransactionResult(
+            redirect_url=f"https://api.provider.com/pay/{self.payment.id}",
+            method="GET"
+        )
+```
+
+### Registering your Processor
+
+Register your processor using entry points in your `pyproject.toml` so it can be discovered by the registry:
+
+```toml
+[project.entry-points."getpaid.backends"]
+my-provider = "my_package.processors:MyPaymentProcessor"
+```
+
+## Architecture Overview
+
+- **BaseProcessor**: The abstract base class that all payment gateway plugins must implement. It provides the standard interface for transaction preparation, callback handling, charging, and refunds.
+- **PaymentFlow**: Manages the payment lifecycle using semantic payment update objects. It ensures that payments move between states (e.g., `NEW` -> `PREPARED` -> `PAID`) according to strict business rules.
+- **PluginRegistry**: A central service for discovering and managing payment processors registered via `getpaid.backends` entry points.
+- **State Engine**: Applies semantic payment and fraud events to payment objects, merges provider metadata, and tracks idempotent provider event IDs.
+
+## API Summary
+
+| Class / Module | Role |
+| --- | --- |
+| `BaseProcessor` | Abstract base for implementing payment gateways. |
+| `PaymentFlow` | Semantic orchestration for payment lifecycles. |
+| `PaymentStatus` | Enum for all possible payment states (NEW, PAID, FAILED, etc.). |
+| `registry` | Singleton registry for backend discovery. |
+| `TransactionResult` | Standard response for transaction initiation. |
+| `GetPaidException` | Base exception for all payment-related errors. |
+
+## Ecosystem
+
+`getpaid-core` is the heart of a larger ecosystem designed to make payment processing easy in any Python web application.
+
+### Framework Wrappers
+- [django-getpaid](https://github.com/django-getpaid/django-getpaid) — Official Django integration.
+- [litestar-getpaid](https://github.com/django-getpaid/litestar-getpaid) — Official Litestar integration.
+- [fastapi-getpaid](https://github.com/django-getpaid/fastapi-getpaid) — Official FastAPI integration.
+
+### Processor Plugins
+- [python-getpaid-payu](https://github.com/django-getpaid/python-getpaid-payu) — PayU backend.
+- [python-getpaid-paynow](https://github.com/django-getpaid/python-getpaid-paynow) — Paynow backend.
+- [python-getpaid-bitpay](https://github.com/django-getpaid/python-getpaid-bitpay) — BitPay backend.
+- [python-getpaid-przelewy24](https://github.com/django-getpaid/python-getpaid-przelewy24) — Przelewy24 backend.
+
+## License
+
+This project is licensed under the MIT License.

python_getpaid_core-3.0.0a3/README.md

@@ -0,0 +1,82 @@
+# python-getpaid-core
+
+[![PyPI version](https://img.shields.io/pypi/v/python-getpaid-core)](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 core.**
+
+`python-getpaid-core` is the foundation of the Getpaid ecosystem. It provides the abstract interfaces, semantic payment update engine, and plugin registry needed to build a robust payment system without coupling your logic to a specific web framework or payment provider.
+
+## Installation
+
+```bash
+pip install python-getpaid-core
+```
+
+## Quick Start: Creating a Custom Processor
+
+To implement a new payment backend, subclass `BaseProcessor` and implement at least `prepare_transaction`.
+
+```python
+from getpaid_core import BaseProcessor
+from getpaid_core.types import TransactionResult
+
+class MyPaymentProcessor(BaseProcessor):
+    slug = "my-provider"
+    display_name = "My Payment Provider"
+    accepted_currencies = ["USD", "EUR"]
+
+    async def prepare_transaction(self, **kwargs) -> TransactionResult:
+        # Generate payment link or form data
+        return TransactionResult(
+            redirect_url=f"https://api.provider.com/pay/{self.payment.id}",
+            method="GET"
+        )
+```
+
+### Registering your Processor
+
+Register your processor using entry points in your `pyproject.toml` so it can be discovered by the registry:
+
+```toml
+[project.entry-points."getpaid.backends"]
+my-provider = "my_package.processors:MyPaymentProcessor"
+```
+
+## Architecture Overview
+
+- **BaseProcessor**: The abstract base class that all payment gateway plugins must implement. It provides the standard interface for transaction preparation, callback handling, charging, and refunds.
+- **PaymentFlow**: Manages the payment lifecycle using semantic payment update objects. It ensures that payments move between states (e.g., `NEW` -> `PREPARED` -> `PAID`) according to strict business rules.
+- **PluginRegistry**: A central service for discovering and managing payment processors registered via `getpaid.backends` entry points.
+- **State Engine**: Applies semantic payment and fraud events to payment objects, merges provider metadata, and tracks idempotent provider event IDs.
+
+## API Summary
+
+| Class / Module | Role |
+| --- | --- |
+| `BaseProcessor` | Abstract base for implementing payment gateways. |
+| `PaymentFlow` | Semantic orchestration for payment lifecycles. |
+| `PaymentStatus` | Enum for all possible payment states (NEW, PAID, FAILED, etc.). |
+| `registry` | Singleton registry for backend discovery. |
+| `TransactionResult` | Standard response for transaction initiation. |
+| `GetPaidException` | Base exception for all payment-related errors. |
+
+## Ecosystem
+
+`getpaid-core` is the heart of a larger ecosystem designed to make payment processing easy in any Python web application.
+
+### Framework Wrappers
+- [django-getpaid](https://github.com/django-getpaid/django-getpaid) — Official Django integration.
+- [litestar-getpaid](https://github.com/django-getpaid/litestar-getpaid) — Official Litestar integration.
+- [fastapi-getpaid](https://github.com/django-getpaid/fastapi-getpaid) — Official FastAPI integration.
+
+### Processor Plugins
+- [python-getpaid-payu](https://github.com/django-getpaid/python-getpaid-payu) — PayU backend.
+- [python-getpaid-paynow](https://github.com/django-getpaid/python-getpaid-paynow) — Paynow backend.
+- [python-getpaid-bitpay](https://github.com/django-getpaid/python-getpaid-bitpay) — BitPay backend.
+- [python-getpaid-przelewy24](https://github.com/django-getpaid/python-getpaid-przelewy24) — Przelewy24 backend.
+
+## License
+
+This project is licensed under the MIT License.

{python_getpaid_core-0.1.1 → python_getpaid_core-3.0.0a3}/docs/changelog.md

@@ -12,12 +12,11 @@ framework-agnostic library.
 - Fraud status enum (`FraudStatus`) with 4 states
 - Backend method and confirmation method enums
 - `BaseProcessor` abstract class for payment gateway plugins
-- Payment and fraud state machines using `transitions` library
-- Transition guards (`_require_fully_paid`, `_require_fully_refunded`)
-- Amount callbacks (`_store_locked_amount`, `_accumulate_paid_amount`)
-- Fraud message callback (`_store_fraud_message`)
+- Semantic payment and fraud update engine
+- Transition validation with `InvalidTransitionError`
+- Provider metadata merging and callback idempotency tracking
 - `PluginRegistry` with entry-point discovery and manual registration
 - Runtime-checkable protocols: `Payment`, `Order`, `PaymentRepository`
-- Typed data structures: `BuyerInfo`, `ItemInfo`, `ChargeResponse`,
-  `PaymentStatusResponse`, `TransactionResult`
+- Dataclass response types: `BuyerInfo`, `ItemInfo`, `ChargeResult`,
+  `PaymentUpdate`, `RefundResult`, `TransactionResult`
 - Structured exception hierarchy with `context` support

{python_getpaid_core-0.1.1 → python_getpaid_core-3.0.0a3}/docs/concepts.md

@@ -16,45 +16,35 @@ Payments move through these states:
 | `REFUND_STARTED` | `"refund_started"` | Refund initiated |
 | `REFUNDED` | `"refunded"` | Fully refunded or lock released |
 
-## Payment State Transitions
+## Payment Events
 
 ```
-NEW ──────────────────────► PREPARED
- │                             │
- │  confirm_lock               │ confirm_lock
- ▼                             ▼
-PRE_AUTH ◄─────────────────────┘
- │
- ├── confirm_charge_sent ──► IN_CHARGE
- │                             │
- │   confirm_payment           │ confirm_payment
- ▼                             ▼
-PARTIAL ◄──────────────────────┘
- │
- ├── mark_as_paid ──────────► PAID
- │
- ├── start_refund ──────────► REFUND_STARTED
- │                             │
- │   cancel_refund             │ confirm_refund
- ◄─────────────────────────────┘
- │
- └── mark_as_refunded ──────► REFUNDED
-
-NEW/PREPARED/PRE_AUTH ──fail──► FAILED
-PRE_AUTH ──release_lock──────► REFUNDED
+prepared         -> PREPARED
+locked           -> PRE_AUTH
+charge_requested -> IN_CHARGE
+payment_captured -> PARTIAL or PAID
+failed           -> FAILED
+refund_requested -> REFUND_STARTED
+refund_confirmed -> PARTIAL or REFUNDED
+refund_cancelled -> active paid status
+lock_released    -> REFUNDED
 ```
 
-### Transition Guards
+### Transition Rules
 
-Some transitions have guards that raise `MachineError` if conditions aren't met:
+The state engine raises `InvalidTransitionError` when an event is incompatible
+with the current payment state.
 
-- **`mark_as_paid`** requires `is_fully_paid()` — `amount_paid >= amount_required`
-- **`mark_as_refunded`** requires `is_fully_refunded()` — `amount_refunded >= amount_paid`
+- You cannot capture a payment after it is already refunded.
+- You cannot start a refund before the payment has been paid.
+- Refund confirmation moves to `REFUNDED` only when `amount_refunded >= amount_paid`.
 
-### Amount Callbacks
+### Amount Handling
 
-- **`confirm_lock`** stores the locked amount via `_store_locked_amount`
-- **`confirm_payment`** accumulates paid amount via `_accumulate_paid_amount`
+- `locked_amount` stores a pre-authorized amount.
+- `paid_amount` updates captured funds and may reduce `amount_locked`.
+- `refunded_amount` tracks refund progress.
+- `provider_data` stores provider-specific metadata such as refund IDs and applied callback IDs.
 
 ## Fraud Statuses
 
@@ -103,13 +93,14 @@ class Payment(Protocol):
     currency: str
     status: str
     backend: str
-    external_id: str
-    description: str
+    external_id: str | None
+    description: str | None
     amount_paid: Decimal
     amount_locked: Decimal
     amount_refunded: Decimal
     fraud_status: str
     fraud_message: str
+    provider_data: dict[str, Any]
 ```
 
 ### PaymentRepository Protocol
@@ -162,6 +153,7 @@ raise ChargeFailure("Gateway returned 500", context={"status_code": 500})
 |------|-------------|
 | `BuyerInfo` | TypedDict with `email`, `first_name`, `last_name`, `phone` (all optional) |
 | `ItemInfo` | TypedDict with `name`, `quantity`, `unit_price` |
-| `ChargeResponse` | TypedDict with `amount_charged`, `success`, `async_call` |
-| `PaymentStatusResponse` | TypedDict with `amount`, `status`, `external_id` (all optional) |
-| `TransactionResult` | TypedDict with `redirect_url`, `form_data`, `method`, `headers` |
+| `ChargeResult` | Dataclass with `amount_charged`, `success`, `async_call`, `provider_data` |
+| `PaymentUpdate` | Dataclass describing semantic payment/fraud events and amounts |
+| `RefundResult` | Dataclass with refund amount and provider metadata |
+| `TransactionResult` | Dataclass with redirect, method, external ID, and provider metadata |

{python_getpaid_core-0.1.1 → python_getpaid_core-3.0.0a3}/docs/getting-started.md

@@ -77,21 +77,30 @@ from getpaid_core.registry import registry
 registry.register(MyGatewayProcessor)
 ```
 
-## Payment State Machine
+## Payment Updates
 
-Payments move through states via an FSM powered by the `transitions` library.
-The machine attaches trigger methods directly to payment objects:
+Payments move through states by applying semantic `PaymentUpdate` objects.
+Processors return updates from callbacks and status polling, and the flow
+applies them to the payment object:
 
 ```python
-from getpaid_core.fsm import create_payment_machine
-
-machine = create_payment_machine(payment)
+from decimal import Decimal
 
-# Now payment has trigger methods:
-payment.confirm_prepared()   # NEW -> PREPARED
-payment.confirm_lock(amount=100)  # PREPARED -> PRE_AUTH
-payment.confirm_payment(amount=100)  # PRE_AUTH -> PARTIAL
-payment.mark_as_paid()       # PARTIAL -> PAID (if fully paid)
+from getpaid_core.fsm import apply_payment_update
+from getpaid_core.types import PaymentUpdate
+
+apply_payment_update(
+    payment,
+    PaymentUpdate(payment_event="prepared"),
+)
+
+apply_payment_update(
+    payment,
+    PaymentUpdate(
+        payment_event="payment_captured",
+        paid_amount=Decimal("100.00"),
+    ),
+)
 ```
 
-See {doc}`concepts` for the full state diagram and transition rules.
+See {doc}`concepts` for the lifecycle rules and semantic event mapping.

{python_getpaid_core-0.1.1 → python_getpaid_core-3.0.0a3}/docs/reference.md

@@ -16,7 +16,7 @@
    :undoc-members:
 ```
 
-## FSM
+## State Engine
 
 ```{eval-rst}
 .. automodule:: getpaid_core.fsm

{python_getpaid_core-0.1.1 → python_getpaid_core-3.0.0a3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = 'python-getpaid-core'
-version = "0.1.1"
+dynamic = ["version"]
 description = 'Framework-agnostic payment processing core.'
 readme = 'README.md'
 license = {text = 'MIT'}
@@ -52,6 +52,9 @@ build-backend = 'hatchling.build'
 [tool.hatch.build.targets.wheel]
 packages = ['src/getpaid_core']
 
+[tool.hatch.version]
+path = "src/getpaid_core/__init__.py"
+
 [tool.pytest.ini_options]
 testpaths = ['tests']
 asyncio_mode = 'auto'

{python_getpaid_core-0.1.1 → python_getpaid_core-3.0.0a3}/src/getpaid_core/__init__.py

@@ -1,10 +1,12 @@
 """Getpaid Core -- framework-agnostic payment processing."""
 
-__version__ = "0.1.0"
+__version__ = "3.0.0a3"
 
 from getpaid_core.enums import BackendMethod
 from getpaid_core.enums import ConfirmationMethod
+from getpaid_core.enums import FraudEvent
 from getpaid_core.enums import FraudStatus
+from getpaid_core.enums import PaymentEvent
 from getpaid_core.enums import PaymentStatus
 from getpaid_core.exceptions import ChargeFailure
 from getpaid_core.exceptions import CommunicationError
@@ -16,24 +18,36 @@ 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 PluginRegistry
 from getpaid_core.registry import registry
+from getpaid_core.types import ChargeResult
+from getpaid_core.types import PaymentUpdate
+from getpaid_core.types import RefundResult
+from getpaid_core.types import TransactionResult
 
 
 __all__ = [
     "BackendMethod",
     "BaseProcessor",
     "ChargeFailure",
+    "ChargeResult",
     "CommunicationError",
     "ConfirmationMethod",
     "CredentialsError",
+    "FraudEvent",
     "FraudStatus",
     "GetPaidException",
     "InvalidCallbackError",
     "InvalidTransitionError",
     "LockFailure",
+    "PaymentEvent",
     "PaymentFlow",
     "PaymentStatus",
+    "PaymentUpdate",
+    "PluginRegistry",
     "RefundFailure",
+    "RefundResult",
+    "TransactionResult",
     "__version__",
     "registry",
 ]

python_getpaid_core-3.0.0a3/src/getpaid_core/backends/dummy.py

@@ -0,0 +1,145 @@
+"""Dummy payment backend for development and testing."""
+
+from collections.abc import Sequence
+from decimal import Decimal
+from typing import ClassVar
+
+from getpaid_core.enums import BackendMethod
+from getpaid_core.enums import FraudEvent
+from getpaid_core.enums import PaymentEvent
+from getpaid_core.processor import BaseProcessor
+from getpaid_core.types import ChargeResult
+from getpaid_core.types import PaymentUpdate
+from getpaid_core.types import RefundResult
+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[Sequence[str]] = (
+        "PLN",
+        "EUR",
+        "USD",
+        "GBP",
+        "CHF",
+        "CZK",
+    )
+
+    async def prepare_transaction(self, **kwargs) -> TransactionResult:
+        method = BackendMethod(self.get_setting("method", BackendMethod.REST))
+        if method is BackendMethod.POST:
+            return TransactionResult(
+                method=method,
+                redirect_url="https://dummy.example.com/form",
+                form_data={
+                    "payment_id": self.payment.id,
+                    "amount": f"{self.payment.amount_required:.2f}",
+                    "currency": self.payment.currency,
+                },
+            )
+
+        return TransactionResult(
+            method=method,
+            redirect_url=f"https://dummy.example.com/pay/{self.payment.id}",
+        )
+
+    async def handle_callback(
+        self, data: dict, headers: dict, **kwargs
+    ) -> PaymentUpdate | None:
+        event = data.get("event")
+        if event == "payment_confirmed":
+            amount = Decimal(
+                str(data.get("paid_amount", self.payment.amount_required))
+            )
+            return PaymentUpdate(
+                payment_event=PaymentEvent.PAYMENT_CAPTURED,
+                paid_amount=amount,
+                provider_event_id=str(
+                    data.get("event_id", f"payment:{self.payment.id}")
+                ),
+            )
+        if event == "payment_failed":
+            return PaymentUpdate(payment_event=PaymentEvent.FAILED)
+        if event == "payment_locked":
+            amount = Decimal(
+                str(data.get("locked_amount", self.payment.amount_required))
+            )
+            return PaymentUpdate(
+                payment_event=PaymentEvent.LOCKED,
+                locked_amount=amount,
+            )
+        if event == "refund_confirmed":
+            amount = Decimal(
+                str(data.get("refunded_amount", self.payment.amount_paid))
+            )
+            return PaymentUpdate(
+                payment_event=PaymentEvent.REFUND_CONFIRMED,
+                refunded_amount=amount,
+                provider_event_id=str(
+                    data.get("event_id", f"refund:{self.payment.id}")
+                ),
+            )
+        if event == "refund_cancelled":
+            return PaymentUpdate(payment_event=PaymentEvent.REFUND_CANCELLED)
+        if event == "fraud_review":
+            return PaymentUpdate(
+                fraud_event=FraudEvent.REVIEW,
+                fraud_message="Manual review required",
+            )
+        if event == "fraud_rejected":
+            return PaymentUpdate(
+                fraud_event=FraudEvent.REJECT,
+                fraud_message="Rejected by dummy backend",
+            )
+        if event == "fraud_accepted":
+            return PaymentUpdate(
+                fraud_event=FraudEvent.ACCEPT,
+                fraud_message="Accepted by dummy backend",
+            )
+        return None
+
+    async def fetch_payment_status(self, **kwargs) -> PaymentUpdate | None:
+        event = self.get_setting("confirmation_event", "payment_confirmed")
+        if event == "payment_locked":
+            return PaymentUpdate(
+                payment_event=PaymentEvent.LOCKED,
+                locked_amount=self.payment.amount_required,
+                provider_event_id=f"pull-lock:{self.payment.id}",
+            )
+        if event == "payment_failed":
+            return PaymentUpdate(
+                payment_event=PaymentEvent.FAILED,
+                provider_event_id=f"pull-fail:{self.payment.id}",
+            )
+        return PaymentUpdate(
+            payment_event=PaymentEvent.PAYMENT_CAPTURED,
+            paid_amount=self.payment.amount_required,
+            provider_event_id=f"pull-pay:{self.payment.id}",
+        )
+
+    async def charge(
+        self, amount: Decimal | None = None, **kwargs
+    ) -> ChargeResult:
+        charged = amount if amount is not None else self.payment.amount_required
+        return ChargeResult(
+            amount_charged=charged,
+            success=True,
+            async_call=bool(kwargs.get("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
+    ) -> RefundResult:
+        return RefundResult(
+            amount=amount if amount is not None else self.payment.amount_paid,
+            provider_data={"refund_id": f"dummy-refund-{self.payment.id}"},
+        )
+
+    async def cancel_refund(self, **kwargs) -> bool:
+        return True

{python_getpaid_core-0.1.1 → python_getpaid_core-3.0.0a3}/src/getpaid_core/enums.py

@@ -1,7 +1,4 @@
-"""Payment processing enums.
-
-Values are kept identical to django-getpaid for backward compatibility.
-"""
+"""Payment processing enums."""
 
 from enum import StrEnum
 
@@ -29,6 +26,28 @@ class FraudStatus(StrEnum):
     CHECK = "check"
 
 
+class PaymentEvent(StrEnum):
+    """Semantic payment lifecycle events reported by processors."""
+
+    PREPARED = "prepared"
+    LOCKED = "locked"
+    CHARGE_REQUESTED = "charge_requested"
+    PAYMENT_CAPTURED = "payment_captured"
+    FAILED = "failed"
+    REFUND_REQUESTED = "refund_requested"
+    REFUND_CONFIRMED = "refund_confirmed"
+    REFUND_CANCELLED = "refund_cancelled"
+    LOCK_RELEASED = "lock_released"
+
+
+class FraudEvent(StrEnum):
+    """Semantic fraud review events reported by processors."""
+
+    REVIEW = "review"
+    ACCEPT = "accept"
+    REJECT = "reject"
+
+
 class BackendMethod(StrEnum):
     """HTTP method used to initiate payment."""