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

python_getpaid_paynow-3.0.0/.github/release-drafter.yml

@@ -0,0 +1,31 @@
+name-template: 'v$RESOLVED_VERSION'
+tag-template: 'v$RESOLVED_VERSION'
+categories:
+  - title: ':boom: Breaking Changes'
+    label: 'breaking'
+  - title: ':rocket: Features'
+    label: 'enhancement'
+  - title: ':fire: Removals and Deprecations'
+    label: 'removal'
+  - title: ':beetle: Fixes'
+    label: 'bug'
+  - title: ':racehorse: Performance'
+    label: 'performance'
+  - title: ':rotating_light: Testing'
+    label: 'testing'
+  - title: ':construction_worker: Continuous Integration'
+    label: 'ci'
+  - title: ':books: Documentation'
+    label: 'documentation'
+  - title: ':hammer: Refactoring'
+    label: 'refactoring'
+  - title: ':lipstick: Style'
+    label: 'style'
+  - title: ':package: Dependencies'
+    labels:
+      - 'dependencies'
+      - 'build'
+template: |
+  ## Changes
+
+  $CHANGES

python_getpaid_paynow-3.0.0/.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+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: Type check with ty
+        run: uv run ty check
+
+      - name: Audit dependencies
+        run: uv run pip-audit --strict
+
+      - name: Run tests
+        run: uv run pytest --tb=short

python_getpaid_paynow-3.0.0/.github/workflows/release.yml

@@ -0,0 +1,70 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+      - master
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out the repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Full history needed for version detection
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        run: pip install uv
+
+      # Version is read from __init__.py (dynamic via hatch)
+      - name: Detect version from __init__.py
+        id: get-version
+        run: |
+          init_py=$(grep -A2 '\[tool\.hatch\.version\]' pyproject.toml | grep '^path\s*=' | head -1 | sed -E "s/path\s*=\s*['\"]([^'\"]+)['\"].*/\1/")
+          version=$(grep '__version__' "$init_py" | head -1 | sed -E "s/.*= ['\"]([^'\"]+)['\"].*/\1/")
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+
+      - name: Check if tag already exists
+        id: check-tag
+        run: |
+          tag="v${{ steps.get-version.outputs.version }}"
+          if git rev-parse "$tag" >/dev/null 2>&1; then
+            echo "already_tagged=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "already_tagged=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Tag new version
+        if: steps.check-tag.outputs.already_tagged == 'false'
+        run: |
+          tag="v${{ steps.get-version.outputs.version }}"
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag -a "$tag" -m "Release $tag"
+          git push origin "$tag"
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish package on PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_TOKEN }}
+
+      - name: Publish the release notes
+        if: steps.check-tag.outputs.already_tagged == 'false'
+        uses: release-drafter/release-drafter@v5.20.0
+        with:
+          publish: true
+          name: v${{ steps.get-version.outputs.version }}
+          tag: v${{ steps.get-version.outputs.version }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

{python_getpaid_paynow-0.1.0 → python_getpaid_paynow-3.0.0}/.gitignore

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

python_getpaid_paynow-3.0.0/.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.0/.python-version

@@ -0,0 +1 @@
+3.12

python_getpaid_paynow-3.0.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: python-getpaid-paynow
+Version: 3.0.0
+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: Documentation, https://python-getpaid-paynow.readthedocs.io
+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 :: 5 - Production/Stable
+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.0
+Provides-Extra: simulator
+Requires-Dist: litestar>=2.0; extra == 'simulator'
+Requires-Dist: python-getpaid-simulator>=3.0.0; 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.0`
+- `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.0/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.0`
+- `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.0/docs/changelog.md

@@ -0,0 +1,28 @@
+# Changelog
+
+## v3.0.0 (2026-06-04)
+
+Stable release of the Paynow payment gateway integration.
+
+### Breaking Changes
+
+- Version bumped from `3.0.0a4` to `3.0.0` (stable).
+- Development status changed from `Alpha` to `Production/Stable`.
+- Core dependency floor raised to `>=3.0.0` (from `>=3.0.0a4`).
+
+### Features
+
+- Full Paynow V3 REST API coverage with async HTTP client.
+- HMAC-SHA256 request and notification signature verification.
+- Payment creation with redirect URL support.
+- Notification (PUSH) callback handling with semantic payment updates.
+- Status polling (PULL) via API.
+- Refund lifecycle: create, check status, cancel.
+- Payment methods retrieval.
+- Simulator plugin for local testing via `python-getpaid-simulator`.
+- Support for 4 currencies: PLN, EUR, USD, GBP.
+
+### Migration from alpha
+
+- Update dependency from `python-getpaid-paynow>=3.0.0a4` to `python-getpaid-paynow>=3.0.0`.
+- No API changes — all public interfaces remain stable.

{python_getpaid_paynow-0.1.0 → python_getpaid_paynow-3.0.0}/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.0}/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