Metadata-Version: 2.5
Name: wkassa
Version: 1.1.0
Summary: Universal payment orchestration, custom checkout, wallet ledger and provider SDK for Python 3.14
Author: WKASSA
License: MIT
License-File: LICENSE
Keywords: billing,checkout,ledger,payment-orchestration,payments,providers,wallet,webhooks
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Office/Business :: Financial
Requires-Python: <3.15,>=3.14
Requires-Dist: aiosqlite<1,>=0.20
Requires-Dist: argon2-cffi<26,>=23.1
Requires-Dist: asyncpg<1,>=0.30
Requires-Dist: cryptography<46,>=44
Requires-Dist: fastapi<1,>=0.115
Requires-Dist: httpx<1,>=0.28
Requires-Dist: jinja2<4,>=3.1
Requires-Dist: pydantic-settings<3,>=2.7
Requires-Dist: pydantic<3,>=2.10
Requires-Dist: python-multipart<1,>=0.0.20
Requires-Dist: redis<7,>=5.2
Requires-Dist: sqlalchemy<3,>=2.0
Requires-Dist: structlog<26,>=25.1
Requires-Dist: uvicorn[standard]<1,>=0.34
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == 'dev'
Requires-Dist: pytest-asyncio<1,>=0.25; extra == 'dev'
Requires-Dist: pytest<9,>=8.3; extra == 'dev'
Requires-Dist: ruff<1,>=0.9; extra == 'dev'
Requires-Dist: twine<7,>=6; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material<10,>=9.6; extra == 'docs'
Description-Content-Type: text/markdown

# WKASSA 1.1.0

**Universal payment orchestration + custom checkout + internal ledger SDK for Python 3.14.**

WKASSA is intentionally **not** a new payment processor. It can also act as a client of a separate WKASSA API/orchestrator deployment when no provider adapters are registered. Real-money collection and payouts
are performed by payment providers/banks selected and connected by the merchant. WKASSA
provides the common API, provider routing, webhooks, checkout, billing/ledger foundations,
wallet abstractions, audit and reconciliation around those connections.

## Install

```bash
pip install wkassa
```

## Connect a provider

```python
from wkassa import WKassa

wk = WKassa()

wk.connect_provider(
    "my-provider",
    provider_instance,
    currencies={"RUB"},
    methods={"sbp", "card"},
    priority=10,
)
```

The provider instance must implement the `PaymentProvider` protocol. This keeps real
credentials and the provider's official API contract inside its adapter instead of inside
WKASSA core.

## Unified payment API

```python
payment = await wk.payments.create(
    amount="1990.00",
    currency="RUB",
    method="sbp",
    provider="my-provider",
    description="Order #123",
    return_url="https://shop.example/success",
    idempotency_key="order-123",
)
```

Provider routing can also be automatic:

```python
payment = await wk.payments.create(
    amount="1990.00",
    currency="RUB",
    method="sbp",
)
```

WKASSA chooses a registered provider by currency/method/priority.

## Wallets

WKASSA supports internal ledger wallet abstractions for application balances and internal
transfers. They are **not automatically bank accounts or electronic money accounts**.

```python
wallet = await wk.wallets.create(owner_id="user_123", currency="RUB")
```

If an application lets users store, transfer or withdraw real customer funds, the operator
must assess and satisfy all applicable legal, licensing, KYC/AML, safeguarding and provider
requirements.

## Custom checkout

Use `CheckoutBuilder` to generate a merchant-branded HTML/CSS checkout foundation:

- logo
- background
- colors
- radius
- animation
- payment action URL

For production, serve checkout over HTTPS and isolate merchant-controlled JavaScript from
WKASSA secrets. Never put provider secret keys into browser code.

## Webhooks

WKASSA includes signed webhook helpers with timestamp/replay protection. A production
application should persist event IDs and process them idempotently.

## Architecture

```text
Merchant application
        |
     WKASSA
        |
  Provider Registry
   /      |       PSP-A   PSP-B    Bank/PSP-C
   \      |       /
      real money rail

WKASSA also provides:
- custom checkout
- payment links foundation
- webhooks
- internal ledger/wallet foundation
- refunds
- payout orchestration
- billing foundations
- audit/reconciliation/risk foundations
```

## Build and publish

```bash
python -m pip install -U build twine
python -m build
python -m twine check dist/*
```

TestPyPI first:

```bash
python -m twine upload --repository testpypi dist/*
python -m pip install --index-url https://test.pypi.org/simple/ wkassa
```

Then production PyPI:

```bash
python -m twine upload dist/*
```

Use a PyPI API token, preferably through environment/CI secrets. Never commit it.

## Important

WKASSA does not fabricate bank/PSP endpoints or claim that an SDK install itself provides
authorization to move real money. Each live provider adapter must use that provider's official
API, credentials, certificates and contractual/technical access.
