Вот перевод на русский язык:

Интеграция платежей YooKassa

Новые возможности

Интеграция платёжной системы

• Интеграция с API YooKassa: Полная поддержка оплаты банковскими картами через YooKassa
• Поддержка нескольких способов оплаты: Теперь пользователи могут выбрать между Telegram Stars, YooKassa, Tribute или ручными платежами
• Автоматическая обработка платежей: Мгновенное подтверждение оплаты и пополнение баланса
• Отслеживание статуса платежа: Пользователи могут проверять статус платежа прямо в боте

Улучшения базы данных

• Новая таблица платежей YooKassa: Отдельное хранилище для данных транзакций YooKassa
• Усовершенствованная система транзакций: Улучшенное отслеживание методов оплаты и поддержка внешних ID
• Универсальная миграция базы: Автоматическое создание таблиц для SQLite, PostgreSQL и MySQL

Функции безопасности

• Безопасная валидация вебхуков: Надёжная проверка подписи уведомлений о платежах
• Формирование чеков: Автоматическое создание фискальных чеков с настройкой ставок НДС
• Поддержка идемпотентности: Предотвращает повторную обработку одного и того же платежа

Пользовательский интерфейс

• Обновлённое меню пополнения: Новый пункт «Банковская карта (YooKassa)»
• Проверка статуса платежа: Обновления в реальном времени с удобными индикаторами
• Упрощённый процесс подтверждения: Пошаговые инструкции для оплаты
• Обработка ошибок: Подробные сообщения и резервные варианты

Технические улучшения

Архитектура сервиса

• YooKassaService: Отдельный сервис для работы с API YooKassa
• Улучшенный PaymentService: Единая обработка всех методов оплаты
• Обработчик вебхуков: Отдельный сервер для уведомлений YooKassa
• CRUD-операции: Полный набор операций с платежами YooKassa

Управление конфигурацией

• Переменные окружения: 15+ новых настроек для YooKassa
• Фича-флаги: Лёгкое включение/выключение методов оплаты
• Гибкая настройка чеков: Конфигурация ставок НДС и предмета оплаты
• Управление URL возврата: Автоматическая или кастомная настройка возвратных ссылок

Схема базы данных

-- Новая таблица для платежей YooKassa
CREATE TABLE yookassa_payments (
    id INTEGER PRIMARY KEY,
    user_id INTEGER NOT NULL,
    yookassa_payment_id VARCHAR(255) UNIQUE NOT NULL,
    amount_kopeks INTEGER NOT NULL,
    currency VARCHAR(3) DEFAULT 'RUB',
    status VARCHAR(50) NOT NULL,
    -- ... дополнительные поля
);

Обработка ошибок и логирование

• Подробное логирование: Полное отслеживание процесса платежа
• Восстановление после ошибок: Корректная обработка сбоев API
• Сверка платежей: Автоматические повторные попытки для неудачных вебхуков

Конфигурация

Обязательные переменные окружения

# 💳 YOOKASSA 
# Включение/выключение YooKassa
YOOKASSA_ENABLED=false

# Основные настройки YooKassa (получить в личном кабинете)
YOOKASSA_SHOP_ID=your_shop_id_here
YOOKASSA_SECRET_KEY=your_secret_key_here

# URL для возврата после оплаты (необязательно, по умолчанию t.me/your_bot)
YOOKASSA_RETURN_URL=https://yourdomain.com/payment-success

# Email по умолчанию для чеков (если пользователь не указал свой)
YOOKASSA_DEFAULT_RECEIPT_EMAIL=receipts@yourdomain.com

# Настройки чеков для налоговой
YOOKASSA_VAT_CODE=1
# Коды НДС:
# 1 - НДС не облагается
# 2 - НДС 0%  
# 3 - НДС 10%
# 4 - НДС 20%
# 5 - НДС 10/110
# 6 - НДС 20/120

YOOKASSA_PAYMENT_MODE=full_payment
# Способы расчета:
# full_payment - полная оплата
# partial_payment - частичная оплата  
# advance - аванс
# full_prepayment - полная предоплата
# partial_prepayment - частичная предоплата
# credit - передача в кредит
# credit_payment - оплата кредита

YOOKASSA_PAYMENT_SUBJECT=service
# Предметы расчета:
# commodity - товар
# excise - подакцизный товар  
# job - работа
# service - услуга
# gambling_bet - ставка в азартной игре
# gambling_prize - выигрыш в азартной игре
# lottery - лотерейный билет
# lottery_prize - выигрыш в лотерее
# intellectual_activity - результат интеллектуальной деятельности
# payment - платеж
# agent_commission - агентское вознаграждение
# composite - составной предмет расчета
# another - другое

# Webhook для получения уведомлений от YooKassa
YOOKASSA_WEBHOOK_PATH=/yookassa-webhook
YOOKASSA_WEBHOOK_PORT=8082
YOOKASSA_WEBHOOK_SECRET=ваш_секретный_ключ_для_webhook

Дополнительные настройки

• Пользовательские return-URL
• Кастомизация чеков
• Настройки безопасности вебхуков
• Лимиты суммы платежей

Изменения, нарушающие совместимость

• Новая зависимость: yookassa==3.0.0
• Изменения схемы базы данных (обрабатываются миграцией)
• Новое значение в перечислении способов оплаты

Примечания по миграции

• Автоматическая миграция создаёт таблицу платежей YooKassa
• Существующие данные не изменяются
• Поддержка всех типов баз данных (SQLite, PostgreSQL, MySQL)
• Можно пропустить с помощью переменной SKIP_MIGRATION=true

Новые/изменённые файлы

• app/services/yookassa_service.py — сервис работы с API YooKassa
• app/database/crud/yookassa.py — CRUD-операции
• app/external/yookassa_webhook.py — обработчик вебхуков
• app/handlers/balance.py — обновлённые обработчики пополнения
• app/services/payment_service.py — поддержка YooKassa
• app/config.py — новые настройки YooKassa
• universal_migration.py — обновлённый скрипт миграции
• requirements.txt — добавлен SDK YooKassa

Улучшения безопасности

• Проверка подписи вебхуков исключает несанкционированные подтверждения платежей
• Безопасная работа с метаданными платежей
• Защита от повторной обработки транзакций
• Шифрование данных платежей

Использование

1. Получите учётные данные YooKassa в личном кабинете
2. Настройте переменные окружения
3. Запустите миграцию базы данных
4. Включите YooKassa в конфигурации бота
5. Укажите URL вебхука в кабинете YooKassa

Поддержка

• Минимальная сумма платежа: 100 ₽
• Максимальная сумма: 50 000 ₽
• Поддерживаемые карты: Visa, MasterCard, Мир
• Автоматическое пополнение баланса за несколько секунд