Metadata-Version: 2.4
Name: litestar-getpaid
Version: 0.1.0
Summary: Litestar framework adapter for getpaid payment processing
Project-URL: Homepage, https://github.com/django-getpaid/litestar-getpaid
Project-URL: Documentation, https://litestar-getpaid.readthedocs.io/
Project-URL: Repository, https://github.com/django-getpaid/litestar-getpaid
Project-URL: Changelog, https://github.com/django-getpaid/litestar-getpaid/blob/main/docs/changelog.md
Project-URL: Issue Tracker, https://github.com/django-getpaid/litestar-getpaid/issues
Author: Dominik Kozaczko
License-Expression: MIT
License-File: LICENSE
Keywords: getpaid,litestar,payment-gateway,payment-processing,payments
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
Requires-Python: >=3.12
Requires-Dist: litestar>=2.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: python-getpaid-core>=0.1.0
Provides-Extra: dev
Requires-Dist: aiosqlite>=0.20.0; extra == 'dev'
Requires-Dist: httpx>=0.27.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Requires-Dist: sqlalchemy[asyncio]>=2.0.0; extra == 'dev'
Requires-Dist: ty>=0.0.17; extra == 'dev'
Provides-Extra: docs
Requires-Dist: furo; extra == 'docs'
Requires-Dist: myst-parser; extra == 'docs'
Requires-Dist: sphinx>=7.0; extra == 'docs'
Provides-Extra: sqlalchemy
Requires-Dist: aiosqlite>=0.20.0; extra == 'sqlalchemy'
Requires-Dist: sqlalchemy[asyncio]>=2.0.0; extra == 'sqlalchemy'
Description-Content-Type: text/markdown

# litestar-getpaid

[![PyPI](https://img.shields.io/pypi/v/litestar-getpaid.svg)](https://pypi.org/project/litestar-getpaid/)
[![Python Version](https://img.shields.io/pypi/pyversions/litestar-getpaid)](https://pypi.org/project/litestar-getpaid/)
[![Litestar](https://img.shields.io/badge/Litestar-2.0%2B-202235)](https://litestar.dev/)
[![License](https://img.shields.io/pypi/l/litestar-getpaid)](https://pypi.org/project/litestar-getpaid/)

Multi-broker payment processing framework for Litestar, built on
[getpaid-core](https://github.com/django-getpaid/python-getpaid-core).

> **v0.1.0 (Alpha)** — This is a pre-release. The API may change before the
> stable v1.0 release.

## Features

- Async-native from routes to persistence
- Multiple payment brokers at the same time
- Flexible plugin architecture via getpaid-core
- SQLAlchemy 2.0 async models and repository (optional)
- Webhook callback retry with exponential backoff
- Typed configuration via `pydantic-settings` with env var support
- Plugin discovery and registration at startup
- Litestar Controllers with `Provide()` dependency injection
- REST endpoints for payment CRUD, callbacks, and redirects

## Installation

```bash
pip install litestar-getpaid
```

With SQLAlchemy support:

```bash
pip install litestar-getpaid[sqlalchemy]
```

Or with uv:

```bash
uv add litestar-getpaid
```

Then install a payment backend plugin (check that the plugin supports
getpaid-core v3 before installing):

```bash
pip install python-getpaid-payu
```

## Quick Start

```python
from litestar import Litestar
from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine

from litestar_getpaid.config import GetpaidConfig
from litestar_getpaid.contrib.sqlalchemy.repository import (
    SQLAlchemyPaymentRepository,
)
from litestar_getpaid.contrib.sqlalchemy.retry_store import SQLAlchemyRetryStore
from litestar_getpaid.plugin import create_payment_router

config = GetpaidConfig(
    default_backend="dummy",
    success_url="https://example.com/thank-you",
    failure_url="https://example.com/payment-failed",
    backends={
        "dummy": {"module": "getpaid_core.backends.dummy"},
    },
)

engine = create_async_engine("sqlite+aiosqlite:///payments.db")
session_factory = async_sessionmaker(engine, expire_on_commit=False)

repository = SQLAlchemyPaymentRepository(session_factory)
retry_store = SQLAlchemyRetryStore(session_factory)


# An order resolver maps order IDs to Order objects.
# Your Order class must implement the getpaid-core Order protocol.
class MyOrderResolver:
    async def resolve(self, order_id: str) -> "YourOrderModel":
        async with session_factory() as session:
            order = await session.get(YourOrderModel, order_id)
            if order is None:
                raise KeyError(order_id)
            return order


payment_router = create_payment_router(
    config=config,
    repository=repository,
    retry_store=retry_store,
    order_resolver=MyOrderResolver(),
)

app = Litestar(route_handlers=[payment_router])
```

Start the server:

```bash
litestar --app my_app:app run --reload
```

Replace `my_app:app` with the module path to your `Litestar` application
instance.

The payment endpoints will be available under `/payments/`.

See the [example app](https://github.com/django-getpaid/litestar-getpaid/tree/main/example)
for a fully working project with a built-in payment broker simulator.

## Supported Versions

- **Python:** 3.12+
- **Litestar:** 2.0+
- **SQLAlchemy:** 2.0+ (optional)

## Running Tests

```bash
uv sync
uv run pytest
```

Or with ruff for linting:

```bash
uv run ruff check src/ tests/
```

## Part of the getpaid ecosystem

This package is part of the **getpaid** family of libraries:

- **[python-getpaid-core](https://github.com/django-getpaid/python-getpaid-core)** — framework-agnostic payment processing core
- **[django-getpaid](https://github.com/django-getpaid/django-getpaid)** — Django integration
- **[fastapi-getpaid](https://github.com/django-getpaid/fastapi-getpaid)** — FastAPI integration
- **[litestar-getpaid](https://github.com/django-getpaid/litestar-getpaid)** — Litestar integration (this package)

Payment gateway plugins:

- **[python-getpaid-payu](https://github.com/django-getpaid/python-getpaid-payu)** — PayU
- **[python-getpaid-paynow](https://github.com/django-getpaid/python-getpaid-paynow)** — mBank Paynow
- **[python-getpaid-przelewy24](https://github.com/django-getpaid/python-getpaid-przelewy24)** — Przelewy24

## Credits

Created by [Dominik Kozaczko](https://github.com/dekoza).

## Disclaimer

This project has nothing in common with the
[getpaid](https://code.google.com/archive/p/getpaid/) plone project.

## License

MIT
