Install

pip install aioplatega

uv add aioplatega

Requires Python 3.12 or newer.

Quick start

import asyncio

from aioplatega import PaymentDetails, PaymentMethodInt, Platega


async def main():
    async with Platega(merchant_id="your-id", secret="your-secret") as client:
        result = await client.create_transaction(
            payment_method=PaymentMethodInt.SBP_QR,
            payment_details=PaymentDetails(amount=100.0, currency="RUB"),
            description="Order #42",
        )
        print(result.redirect)


asyncio.run(main())

Send the payer to result.redirect, then wait for the callback.

from aioplatega import PaymentStatus
from aioplatega.exceptions import PlategaValidationError


@app.route("/callback", methods=["POST"])  # Flask
def callback():
    try:
        payload = client.verify_callback(request.headers, request.get_data())
    except PlategaValidationError:
        return "", 401

    if payload.status == PaymentStatus.CONFIRMED:
        mark_paid(payload.payload)
    return "", 200

[!IMPORTANT] Platega authenticates callbacks by echoing your own X-MerchantId and X-Secret back at you. There is no signature over the body, so the comparison is all that stands between you and a forged callback. verify_callback does it with hmac.compare_digest; if you roll your own, do the same.

What it covers

Every endpoint is reachable two ways: a method on the client, or a method object dispatched through it.

from aioplatega.methods import CreateTransaction

result = await client(CreateTransaction(...))

See the API reference for the full surface.

Design

• Fully asynchronous, built on aiohttp with a lazily created connection pool
• Type safe. Pydantic v2 models throughout, complete annotations, mypy --strict clean
• Immutable. Every model is frozen, and tolerant of unknown fields so a new attribute added server side does not break you
• One exception hierarchy. Everything raised derives from PlategaError, including argument errors caught before a request goes out

PlategaError
├── PlategaAPIError
│   ├── PlategaBadRequestError          (400)
│   ├── PlategaUnauthorizedError        (401)
│   ├── PlategaForbiddenError           (403)
│   ├── PlategaNotFoundError            (404)
│   ├── PlategaConflictError            (409)
│   ├── PlategaUnprocessableEntityError (422)
│   ├── PlategaRateLimitError           (429)
│   └── PlategaServerError              (5xx)
├── PlategaNetworkError
├── PlategaValidationError
└── ClientDecodeError

Payouts

Payouts are a separate client, because they are a separate security model: a secret issued once that Platega cannot recover, an HMAC-SHA256 signature over every request, and an idempotency key on every write.

from aioplatega import PayoutClient

async with PayoutClient(merchant_id="your-id", secret="payout-secret") as payouts:
    cards = await payouts.get_cards()
    result = await payouts.create_card_payout(
        card_id=cards[0].card_id,
        amount_rub=1500,
        idempotency_key="order-42-payout",
    )

[!WARNING] Pass your own idempotency_key whenever a retry has to be safe. Without one a fresh key is generated per call, so a retried request counts as a second payout.

The feature is disabled by default on a Platega account and enabled on request.

Contributing

make install     # sync every dependency group and install the pre-commit hooks
make lint        # ruff, formatting, mypy
make test        # pytest with coverage
make docs-serve  # docs with live reload on :8000

Commits follow Conventional Commits; releases are cut from them by release-please.

License

MIT