Getting Started¶

Setup¶

Create a Platega client with your merchant credentials. Credentials are available in your Platega dashboard under Settings.

from aioplatega import Platega

client = Platega(merchant_id="your-merchant-id", secret="your-secret-key")

Tip

Always use the async context manager to ensure proper cleanup of the connection pool:

async with Platega(merchant_id="...", secret="...") as client:
    ...

Creating a transaction¶

from aioplatega import Platega, PaymentMethodInt, PaymentDetails

async with Platega(merchant_id="...", secret="...") as client:
    result = await client.create_transaction(
        payment_method=PaymentMethodInt.SBP_QR,
        payment_details=PaymentDetails(amount=500.0, currency="RUB"),
        description="Order #42",
        return_url="https://example.com/success",
        failed_url="https://example.com/fail",
    )

    print(result.transaction_id)  # UUID
    print(result.status)          # "PENDING"
    print(result.redirect)        # URL to redirect user to

Note

The transactionId is generated by the Platega system automatically — do not pass an id field in the request.

Checking transaction status¶

result = await client.get_transaction_status("transaction-uuid")

print(result.status)           # "PENDING" | "CONFIRMED" | "CANCELED" | "CHARGEBACKED"
print(result.payment_details)  # PaymentDetails or None

Getting exchange rate¶

rate = await client.get_rate(
    payment_method=2,
    currency_from="RUB",
    currency_to="USDT",
)

print(rate.rate)         # float, e.g. 0.0105
print(rate.updated_at)   # datetime

Getting conversions¶

conversions = await client.get_conversions(
    from_date="2025-01-01T00:00:00Z",
    to_date="2025-12-31T23:59:59Z",
    page=0,
    size=50,
)

for item in conversions.content:
    print(item.id, item.amount, item.currency, item.status)

print(f"Total: {conversions.total_elements}")

Error handling¶

from aioplatega.exceptions import (
    PlategaError,
    PlategaBadRequestError,
    PlategaUnauthorizedError,
    PlategaNetworkError,
)

try:
    result = await client.create_transaction(...)
except PlategaBadRequestError as e:
    print(f"Bad request: {e.message}, status={e.status_code}")
except PlategaUnauthorizedError:
    print("Invalid credentials")
except PlategaNetworkError as e:
    print(f"Network error: {e}")
except PlategaError as e:
    print(f"Unexpected error: {e}")

Callback payload¶

When Platega sends a webhook to your server, parse the JSON body:

from aioplatega import CallbackPayload

payload = CallbackPayload.model_validate(request_json)

print(payload.id)              # transaction UUID
print(payload.status)          # "CONFIRMED" | "CANCELED" | "CHARGEBACK"
print(payload.amount)          # float
print(payload.payment_method)  # int

Warning

Callback requirements:

Your endpoint must respond with HTTP 200 within 60 seconds
HTTPS with a valid SSL certificate is mandatory
Up to 3 retries at 5-minute intervals on failure
Configure the URL in dashboard: Settings → Callback URLs

Command pattern¶

You can also use method objects directly (aiogram-style):

from aioplatega.methods import CreateTransaction
from aioplatega import PaymentMethodInt, PaymentDetails

method = CreateTransaction(
    payment_method=PaymentMethodInt.CARDS_RUB,
    payment_details=PaymentDetails(amount=1000.0, currency="RUB"),
)

result = await client(method)