python-getpaid-paynow 0.1.2__tar.gz → 3.0.0a4__tar.gz

python_getpaid_paynow-3.0.0a4/.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.2 → python_getpaid_paynow-3.0.0a4}/.gitignore

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

python_getpaid_paynow-3.0.0a4/.pre-commit-config.yaml

@@ -0,0 +1,15 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.11.12
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

python_getpaid_paynow-3.0.0a4/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: python-getpaid-paynow
+Version: 3.0.0a4
+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
+Project-URL: Changelog, https://github.com/django-getpaid/python-getpaid-paynow/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: httpx>=0.27.0
+Requires-Dist: python-getpaid-core>=3.0.0a3
+Provides-Extra: simulator
+Requires-Dist: litestar>=2.0; extra == 'simulator'
+Requires-Dist: python-getpaid-simulator>=3.0.0a3; extra == 'simulator'
+Description-Content-Type: text/markdown
+
+# 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
+```
+
+Install simulator support only when you want this package to register its local
+simulator plugin with `python-getpaid-simulator`:
+
+```bash
+pip install python-getpaid-paynow[simulator]
+```
+
+This extra installs the simulator host and Litestar dependencies, then exposes
+the `paynow` plugin through the `getpaid.simulator.providers` entry point.
+
+## Simulator Plugin
+
+When `python-getpaid-paynow[simulator]` is installed alongside
+`python-getpaid-simulator`, the simulator host auto-discovers the PayNow
+plugin.
+
+Typical local setup:
+
+```bash
+pip install python-getpaid-simulator python-getpaid-paynow[simulator]
+getpaid-simulator
+```
+
+The plugin contributes:
+
+- PayNow payment and refund simulator API routes under `/paynow/v3/...`
+- PayNow authorization UI at `/sim/paynow/authorize/{payment_id}`
+- PayNow-specific webhook signing and state transitions
+
+Useful simulator environment variables:
+
+- `SIMULATOR_PAYNOW_API_KEY`
+- `SIMULATOR_PAYNOW_SIGNATURE_KEY`
+- `SIMULATOR_PAYNOW_NOTIFY_URL`
+- `SIMULATOR_PLUGIN_FAILURE_MODE` (`warn` or `strict`)
+
+## 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-3.0.0a4/README.md

@@ -0,0 +1,161 @@
+# 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
+```
+
+Install simulator support only when you want this package to register its local
+simulator plugin with `python-getpaid-simulator`:
+
+```bash
+pip install python-getpaid-paynow[simulator]
+```
+
+This extra installs the simulator host and Litestar dependencies, then exposes
+the `paynow` plugin through the `getpaid.simulator.providers` entry point.
+
+## Simulator Plugin
+
+When `python-getpaid-paynow[simulator]` is installed alongside
+`python-getpaid-simulator`, the simulator host auto-discovers the PayNow
+plugin.
+
+Typical local setup:
+
+```bash
+pip install python-getpaid-simulator python-getpaid-paynow[simulator]
+getpaid-simulator
+```
+
+The plugin contributes:
+
+- PayNow payment and refund simulator API routes under `/paynow/v3/...`
+- PayNow authorization UI at `/sim/paynow/authorize/{payment_id}`
+- PayNow-specific webhook signing and state transitions
+
+Useful simulator environment variables:
+
+- `SIMULATOR_PAYNOW_API_KEY`
+- `SIMULATOR_PAYNOW_SIGNATURE_KEY`
+- `SIMULATOR_PAYNOW_NOTIFY_URL`
+- `SIMULATOR_PLUGIN_FAILURE_MODE` (`warn` or `strict`)
+
+## 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.2 → python_getpaid_paynow-3.0.0a4}/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.2 → python_getpaid_paynow-3.0.0a4}/docs/getting-started.md

@@ -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.2 → python_getpaid_paynow-3.0.0a4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = 'python-getpaid-paynow'
-version = "0.1.2"
+dynamic = ["version"]
 description = 'Paynow payment gateway integration for python-getpaid ecosystem.'
 readme = 'README.md'
 license = {text = 'MIT'}
@@ -19,10 +19,16 @@ classifiers = [
     'Typing :: Typed',
 ]
 dependencies = [
-    'python-getpaid-core>=0.1.0',
+    'python-getpaid-core>=3.0.0a3',
     'httpx>=0.27.0',
 ]
 
+[project.optional-dependencies]
+simulator = [
+    'python-getpaid-simulator>=3.0.0a3',
+    'litestar>=2.0',
+]
+
 [dependency-groups]
 dev = [
     'pytest>=8.0',
@@ -45,6 +51,9 @@ Changelog = 'https://github.com/django-getpaid/python-getpaid-paynow/releases'
 [project.entry-points."getpaid.backends"]
 paynow = 'getpaid_paynow.processor:PaynowProcessor'
 
+[project.entry-points."getpaid.simulator.providers"]
+paynow = 'getpaid_paynow.simulator:get_plugin'
+
 [build-system]
 requires = ['hatchling']
 build-backend = 'hatchling.build'
@@ -52,6 +61,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 +120,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.2 → python_getpaid_paynow-3.0.0a4}/src/getpaid_paynow/__init__.py

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