Types

All Pydantic models are immutable (frozen=True) and support extra fields.

Base

class aioplatega.types.base.PlategaObject

Bases: BaseModel

Base model for all Platega API objects.

Frozen, so assignment to a field is rejected rather than validated, and tolerant of unknown fields, so an attribute added server-side does not break existing callers.

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'defer_build': True, 'extra': 'allow', 'frozen': True, 'populate_by_name': True, 'use_enum_values': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class aioplatega.types.base.SequenceResponse

Bases: object

Sequence access for responses whose JSON body is a bare array.

Mixed into a RootModel so callers can iterate the response directly instead of reaching for .root. Deliberately not a generic base class: a parametrised generic keeps the __module__ of the base, which makes autodoc emit it once per parametrisation.

root: Any

PaymentDetails

class aioplatega.types.payment_details.PaymentDetails

Bases: PlategaObject

Amount and currency of a payment.

amount: float

currency: str

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'defer_build': True, 'extra': 'allow', 'frozen': True, 'populate_by_name': True, 'use_enum_values': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

CreateTransactionRequest

class aioplatega.types.create_transaction_request.CreateTransactionRequest

Bases: PlategaObject

Body for creating a transaction.

Note

Do not supply an id. The API generates the transaction id.

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.

payment_method accepts any integer, not only a PaymentMethodInt member. The enum names the documented methods, but the GitBook records that ids 1 through 9 are P2P and a merchant is enabled for whichever their contract covers, so a closed set would lock those merchants out.

payment_method: PaymentMethodInt | int

payment_details: PaymentDetails

description: str | None

return_url: str | None

failed_url: str | None

payload: str | None

metadata: dict[str, Any] | PaymentMetadata | None

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'defer_build': True, 'extra': 'allow', 'frozen': True, 'populate_by_name': True, 'use_enum_values': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

CreateTransactionResponse

class aioplatega.types.create_transaction_response.CreateTransactionResponse

Bases: PlategaObject

A created transaction, including the URL to send the payer to.

payment_method: str | None

transaction_id: UUID

redirect: str | None

return_url: str | None

payment_details: str | PaymentDetails | None

status: PaymentStatus | str

expires_in: str | None

merchant_id: UUID | None

usdt_rate: float | None

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'defer_build': True, 'extra': 'allow', 'frozen': True, 'populate_by_name': True, 'use_enum_values': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

TransactionStatusResponse

class aioplatega.types.transaction_status_response.TransactionStatusResponse

Bases: PlategaObject

Full state of a transaction.

Note

merchant_id accepts both mechantId and merchantId. The API spells it mechantId in the published schema and in its own example; the correct spelling is accepted as well, should the typo ever be fixed server-side.

Several other fields keep the API’s spelling in their aliases for the same reason: comission, comissionUsdt, comissionType.

id: UUID | None

status: PaymentStatus | str | None

payment_details: PaymentDetails | None

merchant_name: str | None

merchant_id: UUID | None

commission: float | None

payment_method: str | None

expires_in: str | None

return_url: str | None

commission_usdt: float | None

amount_usdt: float | None

qr: str | None

pay_form_success_url: str | None

payload: str | None

commission_type: int | None

external_id: str | None

description: str | None

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'defer_build': True, 'extra': 'allow', 'frozen': True, 'populate_by_name': True, 'use_enum_values': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

RateResponse

class aioplatega.types.rate_response.RateResponse

Bases: PlategaObject

An exchange rate between two currencies for a payment method.

Note

updated_at appears in the GitBook example but not in live responses, so it is optional. Rates are directional: a pair the API answers in one direction may return 404 in the other.

id: str | None

merchant_id: str | None

payment_method: int | None

currency_from: str | None

currency_to: str | None

rate: float | None

updated_at: datetime | None

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'defer_build': True, 'extra': 'allow', 'frozen': True, 'populate_by_name': True, 'use_enum_values': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

ConversionItem

class aioplatega.types.conversion_item.ConversionItem

Bases: PlategaObject

One balance-unlock operation: a conversion between two currencies.

Note

Built from live responses. The published example for this endpoint is an empty object, so the specification describes none of these fields.

id: str | None

merchant_id: str | None

exchange_rate: float | None

operation_date: str | None

source_amount: float | None

target_amount: float | None

source_currency: str | None

target_currency: str | None

transactions_start_date: str | None

transactions_end_date: str | None

processed_transactions_count: int | None

description: str | None

created_at: str | None

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'defer_build': True, 'extra': 'allow', 'frozen': True, 'populate_by_name': True, 'use_enum_values': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

ConversionsResponse

class aioplatega.types.conversions_response.ConversionsResponse

Bases: PlategaObject

A page of balance-unlock operations.

Iterating the response yields the operations directly.

Note

The API answers with operations and pagination. Earlier releases modelled content/totalElements, which no live response has ever contained, so the operations were silently dropped and the list always came back empty.

operations: list[ConversionItem]

pagination: Pagination | None

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'defer_build': True, 'extra': 'allow', 'frozen': True, 'populate_by_name': True, 'use_enum_values': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

CallbackPayload

class aioplatega.types.callback_payload.CallbackPayload

Bases: PlategaObject

Body of the transaction-status callback.

Delivered to the callback URL configured in the dashboard, with the X-MerchantId and X-Secret headers for verification. Platega expects a response within 60 seconds and retries up to three times at five-minute intervals.

Note

status is typed as a plain string rather than PaymentStatus. The published schema lists only CONFIRMED and CANCELED, while the same page’s prose adds CHARGEBACKED for refunds, so the field has to admit values the schema does not name.

id: UUID

amount: float

currency: str

status: str

payment_method: int

payload: str | None

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'defer_build': True, 'extra': 'allow', 'frozen': True, 'populate_by_name': True, 'use_enum_values': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

PaymentMetadata

class aioplatega.types.payment_metadata.PaymentMetadata

Bases: PlategaObject

Payer identification sent alongside a payment.

Shops in certain categories are required to send this. Where the requirement applies, omitting user_id disables antifraud protection and can get the shop suspended. Ask your Platega manager whether it applies to yours.

Note

The schema marks both fields required, but they are optional here so that a shop holding only one of them can still send it. Extra keys are preserved, so anything your shop additionally needs can be passed.

user_id: str | None

user_name: str | None

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'defer_build': True, 'extra': 'allow', 'frozen': True, 'populate_by_name': True, 'use_enum_values': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

PaymentLinkResponse

class aioplatega.types.payment_link_response.PaymentLinkResponse

Bases: PlategaObject

Response of POST v2/transaction/process (payer picks the method).

transaction_id: str

status: str

url: str

expires_in: str | None

rate: float | None

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'defer_build': True, 'extra': 'allow', 'frozen': True, 'populate_by_name': True, 'use_enum_values': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

H2HQrResponse

class aioplatega.types.h2h_qr_response.H2HQrResponse

Bases: PlategaObject

Payment details for a host-to-host transaction.

Note

The shape depends on the method. The Apidog docs show an SBP QR (amount and qr); the older GitBook shows P2P bank requisites (account_number, account_name, method). Every field is optional so either answer parses.

amount: float | None

qr: str | None

account_number: str | None

masked_account_number: str | None

account_name: str | None

method: str | None

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'defer_build': True, 'extra': 'allow', 'frozen': True, 'populate_by_name': True, 'use_enum_values': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Balances

class aioplatega.types.balance_item.BalanceItem

Bases: PlategaObject

Merchant balance in a single currency.

amount: float | None

currency: str | None

frozen_balance: float | None

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'defer_build': True, 'extra': 'allow', 'frozen': True, 'populate_by_name': True, 'use_enum_values': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

GET /balance/all returns a bare array. BalancesResponse is RootModel[list[BalanceItem]] — iterate it directly.

Transaction exports

class aioplatega.types.transaction_export_request.TransactionExportRequest

Bases: PlategaObject

Filters shared by the CSV, Excel and JSON transaction exports.

statuses: list[str] | None

payment_methods: list[str] | None

from_date: str | None

to_date: str | None

time_zone_id: str | None

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'defer_build': True, 'extra': 'allow', 'frozen': True, 'populate_by_name': True, 'use_enum_values': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Transaction export rows

class aioplatega.types.transaction_export_item.TransactionExportItem

Bases: PlategaObject

One transaction row from the JSON export.

record_id: str | None

created_at: str | None

amount: float | None

currency_code: str | None

status: str | None

payment_method: str | None

description: str | None

payload: str | None

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'defer_build': True, 'extra': 'allow', 'frozen': True, 'populate_by_name': True, 'use_enum_values': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

The JSON export returns a bare array. TransactionExportResponse is RootModel[list[TransactionExportItem]] — iterate it directly.

ExportUrlResponse

class aioplatega.types.export_url_response.ExportUrlResponse

Bases: PlategaObject

A link to the generated export file.

url: str

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'defer_build': True, 'extra': 'allow', 'frozen': True, 'populate_by_name': True, 'use_enum_values': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Cancellation

class aioplatega.types.cancel_supported_response.CancelSupportedResponse

Bases: PlategaObject

Whether a transaction can be cancelled, and what it would cost.

A supported of False is a normal answer, not an error: read block_reason for why.

supported: bool

total_deduct_usdt: float | None

penalty_native_amount: float | None

penalty_native_currency: str | None

penalty_usdt: float | None

penalty_conversion_rate: float | None

block_reason: str | None

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'defer_build': True, 'extra': 'allow', 'frozen': True, 'populate_by_name': True, 'use_enum_values': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

CancelTransactionResponse

class aioplatega.types.cancel_transaction_response.CancelTransactionResponse

Bases: PlategaObject

Outcome of a cancellation request.

accepted=False with manual_control_required=True means the refund could not be automated and a human has to pick it up.

transaction_id: str | None

accepted: bool | None

manual_control_required: bool | None

message: str | None

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'defer_build': True, 'extra': 'allow', 'frozen': True, 'populate_by_name': True, 'use_enum_values': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Subscription

class aioplatega.types.subscription.Subscription

Bases: PlategaObject

A recurring SBP subscription.

status and interval_unit are deliberately loose. The vendor’s own examples return each of them as a number in the list response and as a word in the single-subscription response (status: 4 versus status: "Active"), so pinning either to one type would reject half the real payloads. See SubscriptionStatus and SubscriptionInterval.

id: str | None

status: str | int | None

amount: float | None

currency_code: str | None

interval_unit: str | int | None

interval_count: int | None

start_at: str | None

next_charge_at: str | None

last_charge_at: str | None

description: str | None

created_at: str | None

customer_email: str | None

charge_metrics: SubscriptionChargeMetrics | None

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'defer_build': True, 'extra': 'allow', 'frozen': True, 'populate_by_name': True, 'use_enum_values': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

SubscriptionPaymentDetails

class aioplatega.types.subscription_payment_details.SubscriptionPaymentDetails

Bases: PlategaObject

Amount, currency and charge period of a subscription.

Distinct from PaymentDetails: a subscription charges repeatedly, so the period is part of the payment details and is required.

Note

amount is an integer here. The subscription create schema types it that way, unlike the one-off payment schema, which takes a number.

amount: int

currency: str

interval: SubscriptionInterval

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'defer_build': True, 'extra': 'allow', 'frozen': True, 'populate_by_name': True, 'use_enum_values': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

SubscriptionChargeMetrics

class aioplatega.types.subscription_charge_metrics.SubscriptionChargeMetrics

Bases: PlategaObject

Charge history of a subscription, as reported alongside it.

charges_total: int | None

charges_success: int | None

charges_failed: int | None

total_amount: float | None

last_charge_at: str | None

next_charge_at: str | None

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'defer_build': True, 'extra': 'allow', 'frozen': True, 'populate_by_name': True, 'use_enum_values': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

SubscriptionListResponse

class aioplatega.types.subscription_list_response.SubscriptionListResponse

Bases: PlategaObject

A page of subscriptions.

items: list[Subscription]

total: int

page: int

size: int

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'defer_build': True, 'extra': 'allow', 'frozen': True, 'populate_by_name': True, 'use_enum_values': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

CreateSubscriptionResponse

class aioplatega.types.create_subscription_response.CreateSubscriptionResponse

Bases: PlategaObject

Response to creating a subscription.

transaction_id is the subscription id — keep it, it is what every later subscription call takes.

payment_method: str | None

transaction_id: str | None

redirect: str | None

status: str | None

merchant_id: str | None

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'defer_build': True, 'extra': 'allow', 'frozen': True, 'populate_by_name': True, 'use_enum_values': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

CancelSubscriptionResponse

class aioplatega.types.cancel_subscription_response.CancelSubscriptionResponse

Bases: PlategaObject

Result of cancelling a subscription. The endpoint is idempotent.

subscription_id: str | None

status: str | None

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'defer_build': True, 'extra': 'allow', 'frozen': True, 'populate_by_name': True, 'use_enum_values': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Subscription callbacks

class aioplatega.types.subscription_callbacks.SubscriptionChargeCallback

Bases: PlategaObject

Callback delivered on every subscription charge, successful or not.

Field names arrive PascalCase here, unlike the camelCase used by the plain transaction callback.

id: str

amount: float

currency: str

status: str

payment_method: int | None

payload: str | None

subscription_id: str | None

next_charge_at: str | None

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'defer_build': True, 'extra': 'allow', 'frozen': True, 'populate_by_name': True, 'use_enum_values': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class aioplatega.types.subscription_callbacks.SubscriptionStatusCallback

Bases: PlategaObject

Callback delivered when a subscription changes state.

Here id is the subscription id, not a transaction id.

id: str

amount: float | None

currency: str | None

status: str

payment_method: int | None

payload: str | None

subscription_id: str | None

next_charge_at: str | None

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'defer_build': True, 'extra': 'allow', 'frozen': True, 'populate_by_name': True, 'use_enum_values': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Saved cards

class aioplatega.types.saved_card.SavedCard

Bases: PlategaObject

A payout card saved by the merchant.

card_id: str | None

masked: str | None

last4: str | None

brand: str | None

label: str | None

status: str | None

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'defer_build': True, 'extra': 'allow', 'frozen': True, 'populate_by_name': True, 'use_enum_values': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

GET /api/v1/cards returns a bare array. SavedCardsResponse is RootModel[list[SavedCard]] — iterate it directly.

Payouts

class aioplatega.types.payout.CardPayoutRequest

Bases: PlategaObject

Body of POST /api/v1/payouts/card-rub.

Supply either card_id or card_number, not both.

card_id: str | None

card_number: str | None

amount_rub: int

payout_method: str

currency_requested: str

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'defer_build': True, 'extra': 'allow', 'frozen': True, 'populate_by_name': True, 'use_enum_values': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class aioplatega.types.payout.CardPayoutResponse

Bases: PlategaObject

A created payout. Status is CREATED immediately after creation.

withdrawal_record_id: str | None

status: str | None

card_masked: str | None

amount_usdt_debited: float | None

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'defer_build': True, 'extra': 'allow', 'frozen': True, 'populate_by_name': True, 'use_enum_values': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].