litestar-getpaid

Multi-broker payment processing framework for Litestar, built on 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

pip install litestar-getpaid

With SQLAlchemy support:

pip install litestar-getpaid[sqlalchemy]

Or with uv:

uv add litestar-getpaid

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

pip install python-getpaid-payu

Quick Start

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:

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 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

uv sync
uv run pytest

Or with ruff for linting:

uv run ruff check src/ tests/

Part of the getpaid ecosystem

This package is part of the getpaid family of libraries:

• python-getpaid-core — framework-agnostic payment processing core
• django-getpaid — Django integration
• fastapi-getpaid — FastAPI integration
• litestar-getpaid — Litestar integration (this package)

Payment gateway plugins:

• python-getpaid-payu — PayU
• python-getpaid-paynow — mBank Paynow
• python-getpaid-przelewy24 — Przelewy24

Credits

Created by Dominik Kozaczko.

Disclaimer

This project has nothing in common with the getpaid plone project.

License

MIT