platega-sdk 0.1.2

Python SDK для Platega Payment API (sync + async)

Platega SDK

Неофициальный Python SDK для работы с Platega Payment API.

Возможности

• Синхронный и асинхронный клиент - выбирайте подходящий режим работы
• Полная поддержка API - все эндпоинты Platega API
• Типизация - полная поддержка type hints и Pydantic моделей
• Обработка ошибок - детальные исключения для каждого типа ошибки
• Автоматические ретраи - настраиваемые повторные попытки при сбоях
• Webhook handler - готовый обработчик для колбэков

Установка

pip install platega-sdk

Или из исходников:

git clone https://github.com/ducklingsam/platega-sdk.git
cd platega-sdk
pip install -e .

Быстрый старт

Синхронный клиент

from platega import PlategaSyncClient, PaymentMethod

with PlategaSyncClient(
    merchant_id="your-merchant-id",
    secret="your-secret-key"
) as client:
    # Создание платежа
    transaction = client.create_transaction(
        payment_method=PaymentMethod.SBP_QR,
        amount=1000.0,
        currency="RUB",
        description="Оплата заказа #123",
        return_url="https://example.com/success",
        failed_url="https://example.com/failed",
    )

    print(f"Ссылка для оплаты: {transaction.redirect}")
    print(f"ID транзакции: {transaction.transaction_id}")

    # Проверка статуса
    status = client.get_transaction_status(transaction.transaction_id)
    print(f"Статус: {status.status}")

Асинхронный клиент

import asyncio
from platega import PlategaClient, PaymentMethod

async def main():
    async with PlategaClient(
        merchant_id="your-merchant-id",
        secret="your-secret-key"
    ) as client:
        transaction = await client.create_transaction(
            payment_method=PaymentMethod.SBP_QR,
            amount=1000.0,
            currency="RUB",
            description="Оплата заказа #123",
            return_url="https://example.com/success",
            failed_url="https://example.com/failed",
        )

        print(f"Ссылка для оплаты: {transaction.redirect}")

asyncio.run(main())

Документация

Инициализация клиента

Оба клиента (PlategaClient и PlategaSyncClient) принимают одинаковые параметры:

client = PlategaSyncClient(
    merchant_id="your-merchant-id",     # Обязательно: ваш MerchantId
    secret="your-secret-key",           # Обязательно: ваш API ключ
    base_url="https://app.platega.io",  # Опционально: базовый URL
    timeout=30.0,                       # Опционально: таймаут в секундах
    max_retries=3,                      # Опционально: количество ретраев
    retry_delay=1.0,                    # Опционально: задержка между ретраями
    enable_logging=False,               # Опционально: включить логи
)

Методы

create_transaction

Создание новой транзакции.

transaction = client.create_transaction(
    payment_method=PaymentMethod.SBP_QR,  # Способ оплаты
    amount=1000.0,                         # Сумма
    currency="RUB",                        # Валюта
    description="Описание платежа",        # Назначение
    return_url="https://example.com/ok",   # URL успеха
    failed_url="https://example.com/fail", # URL ошибки
    payload="custom_data",                 # Опционально: доп. данные
)

get_transaction_status

Получение статуса транзакции.

from uuid import UUID

status = client.get_transaction_status(
    transaction_id=UUID("3fa85f64-5717-4562-b3fc-2c963f66afa6")
)

get_payment_method_rate

Получение курса обмена для платежного метода.

rate = client.get_payment_method_rate(
    payment_method=PaymentMethod.SBP_QR,
    currency_from="RUB",
    currency_to="USDT",
)

get_balance_unlock_operations

Получение конвертаций за период.

from datetime import datetime, timedelta

date_to = datetime.now()
date_from = date_to - timedelta(days=7)

conversions = client.get_balance_unlock_operations(
    date_from=date_from,
    date_to=date_to,
    page=1,
    size=20,
)

PaymentMethod

Доступные способы оплаты:

from platega import PaymentMethod

PaymentMethod.SBP_QR                # 2 - СБП с QR-кодом
PaymentMethod.CARDS_RUB             # 10 - Российские карты
PaymentMethod.CARD_ACQUIRING        # 11 - Карточный эквайринг
PaymentMethod.INTERNATIONAL_ACQUIRING  # 12 - Международный эквайринг
PaymentMethod.CRYPTO                # 13 - Криптовалюта

Webhook Handler

Для обработки колбэков от Platega:

from platega import WebhookHandler

webhook_handler = WebhookHandler(
    merchant_id="your-merchant-id",
    secret="your-secret-key",
    validate_auth=True,
)

# Пример с FastAPI
from fastapi import FastAPI, Request

app = FastAPI()

@app.post("/webhook/platega")
async def platega_webhook(request: Request):
    headers = dict(request.headers)
    payload = await request.json()

    callback_data = webhook_handler.parse_callback(payload, headers)

    if callback_data.status == "CONFIRMED":
        await process_payment(callback_data)
    elif callback_data.status == "CANCELED":
        await cancel_order(callback_data)

    return webhook_handler.create_success_response()

Обработка ошибок

from platega import (
    PlategaError,           # Базовое исключение
    AuthenticationError,    # 401 - неверные credentials
    ValidationError,        # 400 - ошибка валидации
    NotFoundError,          # 404 - не найдено
    RateLimitError,         # 429 - лимит запросов
    ServerError,            # 5xx - ошибка сервера
    NetworkError,           # Проблемы с сетью
    WebhookValidationError, # Ошибка валидации webhook
)

try:
    transaction = client.create_transaction(...)
except AuthenticationError as e:
    print(f"Проверьте credentials: {e.message}")
except ValidationError as e:
    print(f"Неверные данные: {e.message}")
except PlategaError as e:
    print(f"Ошибка: {e.message}")

Тестирование

pip install -e ".[dev]"
pytest
pytest --cov=platega --cov-report=html

Лицензия

MIT