Client#

class aioplatega.client.platega.Platega[source]#

Bases: object

Async client for the Platega payment API.

Example

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

__init__(merchant_id, secret, session=None)[source]#

Initialize the Platega client.

Parameters:

merchant_id (str) – Your Platega merchant identifier.
secret (str) – Your Platega secret key.
session (BaseSession | None) – Optional custom session. If not provided, an AiohttpSession is created automatically.

Return type:

None

async create_transaction(*, payment_method, payment_details, description=None, return_url=None, failed_url=None, payload=None, metadata=None)[source]#

Create a new payment transaction.

Parameters:

payment_method (PaymentMethodInt | int) – Payment method identifier, e.g. PaymentMethodInt.SBP_QR. Any integer the merchant is enabled for is accepted, including ids the enum does not name.
payment_details (PaymentDetails) – Amount and currency for the payment.
description (str | None) – Optional human-readable description.
return_url (str | None) – URL to redirect the user after successful payment.
failed_url (str | None) – URL to redirect the user after failed payment.
payload (str | None) – Arbitrary string passed through to the callback.
metadata (dict[str, Any] | PaymentMetadata | None) – Extra data required for some merchant categories.

Return type:

CreateTransactionResponse

Returns:

Response containing the transaction ID, status, and redirect URL.

Raises:

PlategaValidationError – If the arguments are not a valid request.

Note: metadata carries the payer identifier. Shops in certain categories are required to send metadata.userId; where that requirement applies, omitting it disables antifraud protection and can get the shop suspended. Ask your Platega manager whether it applies to yours.

async get_transaction_status(transaction_id)[source]#

Get the current status of a transaction.

Parameters:: transaction_id (str | UUID) – UUID of the transaction to query, as a UUID or its string form.
Return type:: TransactionStatusResponse
Returns:: Full transaction details including status and payment info.
Raises:: PlategaValidationError – If transaction_id is not a valid UUID.

async get_rate(*, payment_method, currency_from, currency_to)[source]#

Get the current exchange rate for a payment method.

Parameters:

payment_method (PaymentMethodInt | int) – Payment method identifier, e.g. PaymentMethodInt.SBP_QR.
currency_from (str) – Source currency code (e.g. "USDT").
currency_to (str) – Target currency code (e.g. "RUB").

Return type:

RateResponse

Returns:

Current rate and last update timestamp.

Raises:

PlategaValidationError – If the arguments are not a valid request.

Note

Documented in the older GitBook rather than at https://docs.platega.io, which does not list this endpoint at all. It is live, but treat the omission as a sign that it may be withdrawn without notice.

async get_conversions(*, from_date=None, to_date=None, page=0, size=20)[source]#

Get a paginated list of balance-unlock (conversion) operations.

Parameters:

from_date (str | None) – Start date filter (ISO format string).
to_date (str | None) – End date filter (ISO format string).
page (int) – Zero-based page number.
size (int) – Number of items per page.

Return type:

ConversionsResponse

Returns:

Paginated response with conversion items.

Raises:

PlategaValidationError – If the arguments are not a valid request.

async create_payment_link(*, payment_details, description=None, return_url=None, failed_url=None, payload=None, metadata=None)[source]#

Create a payment link and let the payer choose the method.

Unlike create_transaction(), no payment method is fixed up front: the payer picks one on the hosted page.

Parameters:

payment_details (PaymentDetails) – Amount and currency for the payment.
description (str | None) – Human-readable description shown to the payer.
return_url (str | None) – Where to send the payer after a successful payment.
failed_url (str | None) – Where to send the payer after a failed payment.
payload (str | None) – Arbitrary string passed through to the callback.
metadata (dict[str, Any] | PaymentMetadata | None) – Extra data required for some merchant categories.

Return type:

PaymentLinkResponse

Returns:

The hosted payment URL, transaction id, status and rate.

Raises:

PlategaValidationError – If the arguments are not a valid request.

async get_h2h_qr(transaction_id)[source]#

Get the QR code or payment link for a host-to-host transaction.

Parameters:: transaction_id (str | UUID) – UUID of the transaction, as a UUID or its string form.
Return type:: H2HQrResponse
Returns:: The amount and the QR payload or link.
Raises:: PlategaValidationError – If transaction_id is not a valid UUID.

async get_balances()[source]#

Get merchant balances, one entry per currency.

Return type:: BalancesResponse
Returns:: An iterable of BalanceItem.

Example

for balance in await client.get_balances():
    print(balance.currency, balance.amount)

async check_cancel_supported(transaction_id)[source]#

Check whether a transaction can be cancelled, and what it costs.

Parameters:: transaction_id (str | UUID) – UUID of the transaction, as a UUID or its string form.
Return type:: CancelSupportedResponse
Returns:: Whether cancellation is possible and the USDT it would deduct. A supported of False is a normal answer, not an error; read block_reason for why.
Raises:: PlategaValidationError – If transaction_id is not a valid UUID.

async cancel_transaction(transaction_id)[source]#

Cancel a transaction and refund the payer.

Parameters:: transaction_id (str | UUID) – UUID of the transaction, as a UUID or its string form.
Return type:: CancelTransactionResponse
Returns:: The outcome. An accepted of False with manual_control_required set means a human has to pick it up.
Raises:: PlategaValidationError – If transaction_id is not a valid UUID.

Note

Call check_cancel_supported() first to learn whether the cancellation is possible and what it will cost.

async export_transactions_csv(*, statuses=None, payment_methods=None, from_date=None, to_date=None, time_zone_id=None)[source]#

Export filtered transactions to CSV.

Parameters:

statuses (list[str] | None) – Restrict to these transaction statuses.
payment_methods (list[str] | None) – Restrict to these payment method names.
from_date (str | None) – Start of the period, as an ISO date string.
to_date (str | None) – End of the period, as an ISO date string.
time_zone_id (str | None) – Time zone the dates are expressed in, e.g. "Europe/Moscow".

Return type:

ExportUrlResponse

Returns:

A link to the generated file.

Raises:

PlategaValidationError – If the arguments are not a valid request.

async export_transactions_excel(*, statuses=None, payment_methods=None, from_date=None, to_date=None, time_zone_id=None)[source]#

Export filtered transactions to Excel.

Parameters:

statuses (list[str] | None) – Restrict to these transaction statuses.
payment_methods (list[str] | None) – Restrict to these payment method names.
from_date (str | None) – Start of the period, as an ISO date string.
to_date (str | None) – End of the period, as an ISO date string.
time_zone_id (str | None) – Time zone the dates are expressed in, e.g. "Europe/Moscow".

Return type:

ExportUrlResponse

Returns:

A link to the generated file.

Raises:

PlategaValidationError – If the arguments are not a valid request.

async export_transactions_json(*, statuses=None, payment_methods=None, from_date=None, to_date=None, time_zone_id=None)[source]#

Export filtered transactions as JSON rows.

Unlike the CSV and Excel exports, this returns the rows inline rather than a download link.

Parameters:

statuses (list[str] | None) – Restrict to these transaction statuses.
payment_methods (list[str] | None) – Restrict to these payment method names.
from_date (str | None) – Start of the period, as an ISO date string.
to_date (str | None) – End of the period, as an ISO date string.
time_zone_id (str | None) – Time zone the dates are expressed in, e.g. "Europe/Moscow".

Return type:

TransactionExportResponse

Returns:

An iterable of TransactionExportItem.

Raises:

PlategaValidationError – If the arguments are not a valid request.

async create_subscription(*, payment_details, description=None)[source]#

Create a recurring SBP subscription.

Parameters:

payment_details (SubscriptionPaymentDetails) – Amount, currency and charge period. The period is required — see SubscriptionPaymentDetails.
description (str | None) – Shown to the payer on the payment form and in the email sent after each charge.

Return type:

CreateSubscriptionResponse

Returns:

The subscription, including the redirect URL to send the payer to so they can confirm the mandate.

Raises:

PlategaValidationError – If the arguments are not a valid request.

Note

transaction_id in the response is the subscription id. Keep it: every later subscription call takes it.

async get_subscription(subscription_id)[source]#

Get a single subscription by id.

Parameters:: subscription_id (str | UUID) – UUID of the subscription, as a UUID or its string form.
Return type:: Subscription
Returns:: The subscription and its charge schedule.
Raises:: PlategaValidationError – If subscription_id is not a valid UUID.

async list_subscriptions(*, status=None, from_date=None, to_date=None, page=None, size=None)[source]#

List subscriptions, optionally filtered by status and date range.

Parameters:

status (str | None) – Restrict to subscriptions in this state.
from_date (str | None) – Start of the period, as an ISO date string.
to_date (str | None) – End of the period, as an ISO date string.
page (int | None) – Zero-based page number.
size (int | None) – Number of items per page.

Return type:

SubscriptionListResponse

Returns:

One page of subscriptions, with the total count.

Raises:

PlategaValidationError – If the arguments are not a valid request.

async cancel_subscription(subscription_id)[source]#

Cancel a subscription, stopping all future charges.

Parameters:: subscription_id (str | UUID) – UUID of the subscription, as a UUID or its string form.
Return type:: CancelSubscriptionResponse
Returns:: The subscription id and its resulting status.
Raises:: PlategaValidationError – If subscription_id is not a valid UUID.

Note

Idempotent. The payer can also cancel from the link in the emails sent after each charge, which arrives as a SUBSCRIPTION_CANCELLED callback.

verify_callback(headers, body, *, model=<class 'aioplatega.types.callback_payload.CallbackPayload'>)[source]#

Authenticate an incoming callback against this client’s credentials.

Platega authenticates callbacks by echoing your own X-MerchantId and X-Secret back at you; the comparison is done in constant time.

Parameters:

headers (Mapping[str, str]) – Request headers, looked up case-insensitively.
body (str | bytes) – Raw request body.
model (type[Any]) – Model to parse the body into. Pass SubscriptionChargeCallback or SubscriptionStatusCallback for the subscription callbacks.

Return type:

Any

Returns:

The parsed callback body, an instance of model.

Raises:

PlategaValidationError – If the credentials do not match or the body cannot be parsed.

async close()[source]#

Close the underlying HTTP session and release resources.

Return type:: None