python-getpaid-paynow 0.1.0__tar.gz → 3.0.0a3__tar.gz

python_getpaid_paynow-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_paynow-0.1.0 → python_getpaid_paynow-3.0.0a3}/.gitignore

@@ -18,3 +18,4 @@ htmlcov/
 
 # Sphinx build output
 docs/_build/
+uv.lock

{python_getpaid_paynow-0.1.0 → python_getpaid_paynow-3.0.0a3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-getpaid-paynow
-Version: 0.1.0
+Version: 3.0.0a3
 Summary: Paynow payment gateway integration for python-getpaid ecosystem.
 Project-URL: Homepage, https://github.com/django-getpaid/python-getpaid-paynow
 Project-URL: Repository, https://github.com/django-getpaid/python-getpaid-paynow
@@ -18,50 +18,58 @@ Classifier: Topic :: Office/Business :: Financial :: Point-Of-Sale
 Classifier: Typing :: Typed
 Requires-Python: >=3.12
 Requires-Dist: httpx>=0.27.0
-Requires-Dist: python-getpaid-core>=0.1.0
+Requires-Dist: python-getpaid-core>=3.0.0a3
 Description-Content-Type: text/markdown
 
-# getpaid-paynow
+# python-getpaid-paynow
 
-[![PyPI](https://img.shields.io/pypi/v/python-getpaid-paynow.svg)](https://pypi.org/project/python-getpaid-paynow/)
-[![Python Version](https://img.shields.io/pypi/pyversions/python-getpaid-paynow)](https://pypi.org/project/python-getpaid-paynow/)
-[![License](https://img.shields.io/pypi/l/python-getpaid-paynow)](https://github.com/django-getpaid/python-getpaid-paynow/blob/main/LICENSE)
+[![PyPI version](https://img.shields.io/pypi/v/python-getpaid-paynow.svg)](https://pypi.org/project/python-getpaid-paynow/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python versions](https://img.shields.io/pypi/pyversions/python-getpaid-paynow.svg)](https://pypi.org/project/python-getpaid-paynow/)
 
-[Paynow](https://www.paynow.pl/) payment gateway plugin for the
-[python-getpaid](https://github.com/django-getpaid) ecosystem. Provides an
-async HTTP client (`PaynowClient`) and a payment processor (`PaynowProcessor`)
-that integrates with getpaid-core's `BaseProcessor` interface. Authentication
-uses API Key + HMAC-SHA256 signature against the Paynow V3 REST API.
+Paynow payment processor for [python-getpaid](https://github.com/django-getpaid/python-getpaid-core) ecosystem.
+Paynow is a modern Polish payment provider and a subsidiary of mBank.
 
 ## Architecture
 
 The plugin is split into two layers:
 
-- **`PaynowClient`** -- low-level async HTTP client wrapping the Paynow V3
-  REST API. Uses `httpx.AsyncClient` with API Key authentication and
-  HMAC-SHA256 request signing. Can be used standalone or as an async context
-  manager for connection reuse.
-- **`PaynowProcessor`** -- high-level payment processor implementing
-  `BaseProcessor`. Orchestrates payment creation, callback/notification
-  handling, status polling, and refunds. Integrates with the getpaid-core FSM
-  for state transitions.
+- **`PaynowClient`** -- low-level async HTTP client wrapping the Paynow V3 REST API. Uses `httpx.AsyncClient` with API Key authentication and HMAC-SHA256 request signing. Can be used standalone or as an async context manager for connection reuse.
+- **`PaynowProcessor`** -- high-level payment processor implementing `BaseProcessor`. Orchestrates payment creation, callback/notification handling, status polling, and refunds using semantic payment updates.
 
 ## Key Features
 
 - **Create payment** -- register a payment and get a redirect URL
-- **Notification handling** -- verify HMAC signature and process status changes
-- **Status polling** -- fetch current payment status via API
+- **Notification handling** -- verify HMAC-SHA256 signature and process status changes
+- **Status polling** -- fetch current payment status via API (PULL flow)
 - **Refund** -- create, check, and cancel refunds
 - **Payment methods** -- retrieve available payment methods
-- **HMAC-SHA256 signatures** -- automatic request and notification signing
-- **PUSH and PULL** -- notification-based flow with optional status polling
+- **Sandbox mode** -- full support for testing environment
+
+**Note:** Paynow does not support pre-authorization flows. Immediate capture is used for all transactions. The `charge()` and `release_lock()` methods raise `NotImplementedError`.
+
+## Supported Currencies
+
+The processor supports the following 4 currencies:
+- **PLN** (Polish Złoty)
+- **EUR** (Euro)
+- **GBP** (British Pound)
+- **USD** (US Dollar)
+
+## Installation
+
+Install the package using pip:
+
+```bash
+pip install python-getpaid-paynow
+```
 
 ## Quick Usage
 
 ### Standalone Client
 
 ```python
-import asyncio
+import anyio
 from decimal import Decimal
 from getpaid_paynow import PaynowClient
 
@@ -83,19 +91,19 @@ async def main():
         redirect_url = response["redirectUrl"]
         print(f"Redirect buyer to: {redirect_url}")
 
-asyncio.run(main())
+anyio.run(main)
 ```
 
-### With django-getpaid
+### With python-getpaid
 
-Register the plugin via entry point in `pyproject.toml`:
+Register the plugin via entry point in `pyproject.toml` (if not using the pre-packaged version):
 
 ```toml
 [project.entry-points."getpaid.backends"]
 paynow = "getpaid_paynow.processor:PaynowProcessor"
 ```
 
-Then configure in your Django settings (or config dict):
+Then configure in your project settings:
 
 ```python
 GETPAID_BACKEND_SETTINGS = {
@@ -103,8 +111,8 @@ GETPAID_BACKEND_SETTINGS = {
         "api_key": "your-api-key",
         "signature_key": "your-signature-key",
         "sandbox": True,
-        "notification_url": "https://shop.example.com/payments/{payment_id}/callback/",
-        "continue_url": "https://shop.example.com/payments/{payment_id}/return/",
+        "notification_url": "https://your-site.com/payments/{payment_id}/callback/",
+        "continue_url": "https://your-site.com/payments/{payment_id}/return/",
     }
 }
 ```
@@ -119,35 +127,21 @@ GETPAID_BACKEND_SETTINGS = {
 | `notification_url` | `str` | `""` | Notification URL template; use `{payment_id}` placeholder |
 | `continue_url` | `str` | `""` | Return URL template; use `{payment_id}` placeholder |
 
-## Supported Currencies
-
-PLN, EUR, USD, GBP (4 total).
-
-## Limitations
-
-Paynow does not support pre-authorization. The `charge()` and
-`release_lock()` methods raise `NotImplementedError`.
-
 ## Requirements
 
 - Python 3.12+
-- `python-getpaid-core >= 0.1.0`
+- `python-getpaid-core >= 3.0.0a3`
 - `httpx >= 0.27.0`
 
-## Related Projects
+## Links
 
-- [python-getpaid-core](https://github.com/django-getpaid/python-getpaid-core) -- core abstractions (protocols, FSM, processor base class)
-- [django-getpaid](https://github.com/django-getpaid/django-getpaid) -- Django adapter (models, views, admin)
+- **Core Library:** [python-getpaid-core](https://github.com/django-getpaid/python-getpaid-core)
+- **Official Paynow Documentation:** [docs.paynow.pl](https://docs.paynow.pl/)
+- **GitHub Repository:** [django-getpaid/python-getpaid-paynow](https://github.com/django-getpaid/python-getpaid-paynow)
 
 ## License
 
-MIT
-
-## Disclaimer
-
-This project has nothing in common with the
-[getpaid](http://code.google.com/p/getpaid/) plone project.
-It is part of the `django-getpaid` / `python-getpaid` ecosystem.
+This project is licensed under the MIT License.
 
 ## Credits
 

python_getpaid_paynow-3.0.0a3/README.md

@@ -0,0 +1,125 @@
+# python-getpaid-paynow
+
+[![PyPI version](https://img.shields.io/pypi/v/python-getpaid-paynow.svg)](https://pypi.org/project/python-getpaid-paynow/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python versions](https://img.shields.io/pypi/pyversions/python-getpaid-paynow.svg)](https://pypi.org/project/python-getpaid-paynow/)
+
+Paynow payment processor for [python-getpaid](https://github.com/django-getpaid/python-getpaid-core) ecosystem.
+Paynow is a modern Polish payment provider and a subsidiary of mBank.
+
+## Architecture
+
+The plugin is split into two layers:
+
+- **`PaynowClient`** -- low-level async HTTP client wrapping the Paynow V3 REST API. Uses `httpx.AsyncClient` with API Key authentication and HMAC-SHA256 request signing. Can be used standalone or as an async context manager for connection reuse.
+- **`PaynowProcessor`** -- high-level payment processor implementing `BaseProcessor`. Orchestrates payment creation, callback/notification handling, status polling, and refunds using semantic payment updates.
+
+## Key Features
+
+- **Create payment** -- register a payment and get a redirect URL
+- **Notification handling** -- verify HMAC-SHA256 signature and process status changes
+- **Status polling** -- fetch current payment status via API (PULL flow)
+- **Refund** -- create, check, and cancel refunds
+- **Payment methods** -- retrieve available payment methods
+- **Sandbox mode** -- full support for testing environment
+
+**Note:** Paynow does not support pre-authorization flows. Immediate capture is used for all transactions. The `charge()` and `release_lock()` methods raise `NotImplementedError`.
+
+## Supported Currencies
+
+The processor supports the following 4 currencies:
+- **PLN** (Polish Złoty)
+- **EUR** (Euro)
+- **GBP** (British Pound)
+- **USD** (US Dollar)
+
+## Installation
+
+Install the package using pip:
+
+```bash
+pip install python-getpaid-paynow
+```
+
+## Quick Usage
+
+### Standalone Client
+
+```python
+import anyio
+from decimal import Decimal
+from getpaid_paynow import PaynowClient
+
+async def main():
+    async with PaynowClient(
+        api_key="your-api-key",
+        signature_key="your-signature-key",
+        api_url="https://api.sandbox.paynow.pl",
+    ) as client:
+        # Create a payment
+        response = await client.create_payment(
+            amount=Decimal("49.99"),
+            currency="PLN",
+            external_id="order-001",
+            description="Order #001",
+            buyer_email="buyer@example.com",
+            continue_url="https://shop.example.com/return/order-001",
+        )
+        redirect_url = response["redirectUrl"]
+        print(f"Redirect buyer to: {redirect_url}")
+
+anyio.run(main)
+```
+
+### With python-getpaid
+
+Register the plugin via entry point in `pyproject.toml` (if not using the pre-packaged version):
+
+```toml
+[project.entry-points."getpaid.backends"]
+paynow = "getpaid_paynow.processor:PaynowProcessor"
+```
+
+Then configure in your project settings:
+
+```python
+GETPAID_BACKEND_SETTINGS = {
+    "paynow": {
+        "api_key": "your-api-key",
+        "signature_key": "your-signature-key",
+        "sandbox": True,
+        "notification_url": "https://your-site.com/payments/{payment_id}/callback/",
+        "continue_url": "https://your-site.com/payments/{payment_id}/return/",
+    }
+}
+```
+
+## Configuration Reference
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `api_key` | `str` | *required* | API key from Paynow merchant panel |
+| `signature_key` | `str` | *required* | Signature key for HMAC calculation |
+| `sandbox` | `bool` | `True` | Use sandbox or production API |
+| `notification_url` | `str` | `""` | Notification URL template; use `{payment_id}` placeholder |
+| `continue_url` | `str` | `""` | Return URL template; use `{payment_id}` placeholder |
+
+## Requirements
+
+- Python 3.12+
+- `python-getpaid-core >= 3.0.0a3`
+- `httpx >= 0.27.0`
+
+## Links
+
+- **Core Library:** [python-getpaid-core](https://github.com/django-getpaid/python-getpaid-core)
+- **Official Paynow Documentation:** [docs.paynow.pl](https://docs.paynow.pl/)
+- **GitHub Repository:** [django-getpaid/python-getpaid-paynow](https://github.com/django-getpaid/python-getpaid-paynow)
+
+## License
+
+This project is licensed under the MIT License.
+
+## Credits
+
+Created by [Dominik Kozaczko](https://github.com/dekoza).

{python_getpaid_paynow-0.1.0 → python_getpaid_paynow-3.0.0a3}/docs/concepts.md

@@ -23,7 +23,7 @@ The Paynow payment flow follows a create-redirect-notify pattern:
 ┌──────────┐  ◄────────────────────────────────┘
 │  Your    │
 │  Server  │  1. verify_callback (check HMAC signature)
-│          │  2. handle_callback (update FSM state)
+│          │  2. handle_callback (return semantic payment update)
 └──────────┘
 ```
 
@@ -46,8 +46,9 @@ The Paynow payment flow follows a create-redirect-notify pattern:
    mismatch.
 
 5. **Handle callback** — `PaynowProcessor.handle_callback()` maps the Paynow
-   status to FSM transitions: `CONFIRMED` triggers `confirm_payment` +
-   `mark_as_paid`; `REJECTED`, `ERROR`, `EXPIRED`, `ABANDONED` trigger `fail`.
+   status to semantic updates: `CONFIRMED` returns `payment_captured`,
+   `PENDING` returns `prepared`, and `REJECTED`, `ERROR`, `EXPIRED`,
+   `ABANDONED` return `failed`.
 
 :::{note}
 Unlike Przelewy24, Paynow does **not** require a separate verification step
@@ -154,17 +155,17 @@ The plugin supports both notification models:
 
 - **PULL** — `PaynowProcessor.fetch_payment_status()` calls
   `PaynowClient.get_payment_status()` to poll the payment status. Returns a
-  `PaymentStatusResponse` with the mapped FSM trigger.
+  semantic `PaymentUpdate`.
 
-| Paynow Status | Mapped FSM Trigger |
-|---------------|-------------------|
+| Paynow Status | Semantic Event |
+|---------------|----------------|
 | `NEW` | `None` |
-| `PENDING` | `confirm_prepared` |
-| `CONFIRMED` | `confirm_payment` |
-| `REJECTED` | `fail` |
-| `ERROR` | `fail` |
-| `EXPIRED` | `fail` |
-| `ABANDONED` | `fail` |
+| `PENDING` | `prepared` |
+| `CONFIRMED` | `payment_captured` |
+| `REJECTED` | `failed` |
+| `ERROR` | `failed` |
+| `EXPIRED` | `failed` |
+| `ABANDONED` | `failed` |
 
 ## Supported Operations
 

{python_getpaid_paynow-0.1.0 → python_getpaid_paynow-3.0.0a3}/docs/getting-started.md

@@ -32,7 +32,7 @@ The `PaynowClient` is an async HTTP client that wraps the Paynow V3 REST API.
 Use it as an async context manager for connection reuse:
 
 ```python
-import asyncio
+import anyio
 from decimal import Decimal
 from getpaid_paynow import PaynowClient
 
@@ -56,7 +56,7 @@ async def main():
         redirect_url = response["redirectUrl"]
         print(f"Redirect buyer to: {redirect_url}")
 
-asyncio.run(main())
+anyio.run(main)
 ```
 
 ## Using with django-getpaid
@@ -92,7 +92,7 @@ payment ID at runtime.
 ### 3. Process payments
 
 The framework adapter handles the rest — creating payments, redirecting
-buyers, receiving notifications, and updating payment status via the FSM.
+buyers, receiving notifications, and applying semantic payment updates.
 
 ## Sandbox vs Production
 

{python_getpaid_paynow-0.1.0 → python_getpaid_paynow-3.0.0a3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = 'python-getpaid-paynow'
-version = '0.1.0'
+dynamic = ["version"]
 description = 'Paynow payment gateway integration for python-getpaid ecosystem.'
 readme = 'README.md'
 license = {text = 'MIT'}
@@ -19,7 +19,7 @@ classifiers = [
     'Typing :: Typed',
 ]
 dependencies = [
-    'python-getpaid-core>=0.1.0',
+    'python-getpaid-core>=3.0.0a3',
     'httpx>=0.27.0',
 ]
 
@@ -52,6 +52,9 @@ build-backend = 'hatchling.build'
 [tool.hatch.build.targets.wheel]
 packages = ['src/getpaid_paynow']
 
+[tool.hatch.version]
+path = "src/getpaid_paynow/__init__.py"
+
 [tool.pytest.ini_options]
 testpaths = ['tests']
 asyncio_mode = 'auto'
@@ -108,8 +111,6 @@ include = ['tests/**']
 unresolved-attribute = 'ignore'
 invalid-argument-type = 'ignore'
 
-# The processor uses FSM methods (may_trigger, confirm_payment,
-# mark_as_paid, fail) dynamically bound by the transitions library.
 [[tool.ty.overrides]]
 include = ['src/getpaid_paynow/processor.py']
 [tool.ty.overrides.rules]

{python_getpaid_paynow-0.1.0 → python_getpaid_paynow-3.0.0a3}/src/getpaid_paynow/__init__.py

@@ -1,5 +1,7 @@
 """Paynow V3 payment gateway integration for python-getpaid ecosystem."""
 
+__version__ = "3.0.0a3"
+
 __all__ = [
     "PaynowClient",
     "PaynowProcessor",