🟢 Platega Async SDK (Unofficial)

🛠️ A modern, unofficial asynchronous Python SDK for the Platega.io API.
Built with httpx and Pydantic for high performance in async applications like aiogram, FastAPI, or Django Ninja.

---

✨ Features

• Fully Asynchronous: Built with httpx to be non-blocking and perfect for modern async frameworks.
• Type-Safe: Strict request/response validation with Pydantic V2 ensures your code is robust.
• Secure by Default: Includes a helper to verify webhook signatures, protecting you from fake callbacks.
• Clean API: A minimalistic and intuitive interface for creating transactions, fetching statuses, and getting rates.
• Robust Error Handling: Clear, custom exceptions for network and API errors.
• Resource Management: Uses an async context manager (async with) to handle client sessions gracefully.
• Modern Python: Supports Python 3.8+.

---

📦 Installation

pip install plategaio

---

🚀 Quick Start

The client is designed to be used as an asynchronous context manager.

import asyncio
from uuid import uuid4
from plategaio import (
    PlategaAsyncClient,
    CreateTransactionRequest,
    PaymentDetails,
    PlategaAPIError,
)

async def main():
    async with PlategaAsyncClient(
        merchant_id="YOUR_MERCHANT_ID",
        secret="YOUR_SECRET_KEY",
    ) as client:
        try:
            tx_request = CreateTransactionRequest(
                payment_method=2, # SBP
                id=uuid4(),
                payment_details=PaymentDetails(amount=150.50, currency="RUB"),
                description="Order #123",
                return_url="https://your.site/success",
                failed_url="https://your.site/failed",
            )
            tx_response = await client.create_transaction(tx_request)
            print(f"Redirect user to: {tx_response.redirect}")
            
            status = await client.get_transaction_status(tx_response.transaction_id)
            print(f"Transaction status: {status.status}")

            rate = await client.get_rate(
                payment_method=2, 
                currency_from="USDT", 
                currency_to="RUB"
            )
            print(f"Current USDT->RUB rate: {rate.rate}")

        except PlategaAPIError as e:
            print(f"API Error: {e.status_code} - {e.message}")
        except Exception as e:
            print(f"An unexpected error occurred: {e}")

if __name__ == "__main__":
    asyncio.run(main())

---

⚠️ Error Handling

The SDK raises clear, specific exceptions:

• PlategaError: Base exception for the library.
• PlategaNetworkError: Raised for network issues like timeouts or connection errors.
• PlategaAPIError: Raised for non-2xx API responses (e.g., 400, 401, 500). It contains status_code, message, and response_body.

Example:

from plategaio import PlategaAPIError, PlategaNetworkError

try:
    # ... your API call
except PlategaAPIError as e:
    print(f"API returned an error: status={e.status_code}, message='{e.message}'")
except PlategaNetworkError as e:
    print(f"A network error occurred: {e}")

---

📚 API Reference

PlategaAsyncClient

• async create_transaction(payload: CreateTransactionRequest) -> CreateTransactionResponse
• async get_transaction_status(transaction_id: str) -> TransactionStatusResponse
• async get_rate(payment_method: int, currency_from: str, currency_to: str) -> RateResponse
• async close(): Closes the client session. Called automatically when using async with.

---

🌍 Links

• 📦 PyPI
• 💻 Source Code
• 🔗 Platega.io