Merge branch 'pr-27' into dev

# Conflicts:
#	docs/features/payments.md

backend/bot/payment_providers/freekassa.py

@@ -76,7 +76,7 @@ class FreeKassaConfig(ProviderEnvConfig):
     MERCHANT_ID: Optional[str] = None
     FIRST_SECRET: Optional[str] = None
     SECOND_SECRET: Optional[str] = None
-    PAYMENT_URL: str = Field(default="https://pay.freekassa.ru/")
+    PAYMENT_URL: str = Field(default="https://pay.freekassa.net/")
     API_KEY: Optional[str] = None
     PAYMENT_IP: Optional[str] = None
     PAYMENT_METHOD_ID: Optional[int] = None
@@ -723,7 +723,7 @@ _CONFIG_MANIFEST = (
         "FREEKASSA_PAYMENT_URL",
         "url",
         "Payment URL",
-        placeholder="https://pay.freekassa.ru/",
+        placeholder="https://pay.freekassa.net/",
         subsection="FreeKassa",
         attr="PAYMENT_URL",
     ),

docs/features/payments.md

@@ -1,24 +1,30 @@
 # Платежи
 
-Платежные методы включаются настройками и отображаются пользователю как кнопки оплаты в Mini App и Telegram-сценариях. Настройки можно задавать через `.env` или через админку, если параметр есть в allowlist настроек.
+Платежные методы включаются через `.env` или админ-панель, если параметр добавлен в allowlist настроек. В Mini App и Telegram-сценариях включённые методы отображаются как кнопки оплаты.
 
-## Типовой порядок настройки
+## Общий порядок настройки
 
-1. Включите нужный провайдер в админке или через `.env`.
+1. Включите нужный провайдер.
 2. Заполните публичные параметры, секреты и URL возврата.
-3. Настройте URL вебхука у провайдера, если это требуется.
+3. Настройте webhook URL у провайдера, если он используется.
 4. Проверьте порядок методов в `PAYMENT_METHODS_ORDER`.
 5. Проверьте подписи и иконки кнопок оплаты.
-6. Выполните тестовый платеж и проверьте логи `backend`.
+6. Выполните тестовый платеж.
+7. Проверьте логи `backend`.
 
-Общие ссылки:
+> [!NOTE]
+> Если URL возврата не задан явно, используется ссылка на Telegram-бота.
 
-- [Справочник `.env`](../configuration/env-vars.md) содержит все ключи провайдеров.
+## Общие ссылки
-- [Админ-панель](admin-panel.md) описывает UI-настройки платежей.
+
-- [Тарифы](tariffs.md) описывают цены, Telegram Stars и сценарии покупки.
+- [Справочник `.env`](../configuration/env-vars.md) — все ключи платежных провайдеров.
-- [Логи](../troubleshooting/logs.md) помогают проверить webhook и создание платежных ссылок.
+- [Админ-панель](admin-panel.md) — UI-настройки платежей.
+- [Тарифы](tariffs.md) — цены, Telegram Stars и сценарии покупки.
+- [Логи](../troubleshooting/logs.md) — проверка webhook и создания платежных ссылок.
 
 ## Webhook URL провайдеров
+> [!TIP]
+> Готовый URL вебхука отображается вверху раздела каждого провайдера в админ-панели.
 
 Все платежные webhook URL строятся от `WEBHOOK_BASE_URL` - публичного HTTPS-адреса backend/webhook-домена. Это должен быть домен, который проксируется на backend-сервер вебхуков (`backend:8080`), а не `SUBSCRIPTION_MINI_APP_URL` frontend/Mini App. Если `WEBHOOK_BASE_URL=https://bot.example.com`, то полный адрес получается как `https://bot.example.com` + путь из таблицы.
 
@@ -38,180 +44,224 @@
 
 ## YooKassa
 
-YooKassa используется для рублевых оплат и может участвовать в сценариях автопродления period-подписок.
+YooKassa используется для рублевых оплат. Провайдер также может участвовать в сценариях автопродления period-подписок.
 
-Что настроить:
+### Настройка
 
-- включение провайдера: `YOOKASSA_ENABLED`;
+1. Включите `YOOKASSA_ENABLED`.
-- идентификаторы и секреты магазина;
+2. Заполните `YOOKASSA_SHOP_ID`, `YOOKASSA_SECRET_KEY` и `YOOKASSA_RETURN_URL`.
-- URL вебхука: `WEBHOOK_BASE_URL` + `/webhook/yookassa`;
+3. Скопируйте URL вебхука из админ-панели и укажите его в кабинете YooKassa.
-- отображение кнопки оплаты и порядок платежных методов.
 
-Справочник переменных: [YooKassa](../configuration/env-vars.md#yookassa).
+### Справочник
+
+- [YooKassa](../configuration/env-vars.md#yookassa)
 
 ## FreeKassa
 
-FreeKassa подключается как отдельный платежный метод и обрабатывает входящие webhook-события через `backend`.
+FreeKassa подключается как отдельный платежный метод. Входящие webhook-события обрабатываются через `backend`.
 
-Что настроить:
+### Настройка
 
-- включение провайдера: `FREEKASSA_ENABLED`;
+1. Включите `FREEKASSA_ENABLED`.
-- ID магазина, API/secret-ключи и настройки подписи;
+2. Заполните `FREEKASSA_MERCHANT_ID`, `FREEKASSA_FIRST_SECRET`, `FREEKASSA_SECOND_SECRET` и `FREEKASSA_API_KEY`.
-- список доверенных IP, если используется;
+3. Проверьте настройки подписи.
-- публичный URL вебхука: `WEBHOOK_BASE_URL` + `/webhook/freekassa`.
+4. Скопируйте URL вебхука из админ-панели и укажите его в кабинете FreeKassa.
+5. При необходимости заполните `FREEKASSA_TRUSTED_IPS`.
 
-Справочник переменных: [FreeKassa](../configuration/env-vars.md#freekassa).
+### Справочник
+
+- [FreeKassa](../configuration/env-vars.md#freekassa)
 
 ## Platega
 
-Platega подключается как отдельный платежный провайдер, но внутри Minishop может дать несколько кнопок: основную устаревшую кнопку, СБП/карту и крипто-кнопку. Общие параметры мерчанта задаются один раз, а ID методов оплаты и подписи кнопок настраиваются отдельно.
+Platega подключается как отдельный платежный провайдер. Внутри Minishop он может создавать несколько кнопок: основную legacy-кнопку, СБП/карту и crypto-кнопку.
 
-Что включить:
+### Настройка
 
-- `PLATEGA_ENABLED` - общий флаг провайдера;
+1. Включите `PLATEGA_ENABLED`.
-- `PLATEGA_SBP_ENABLED` - отдельная кнопка СБП/карта;
+3. Укажите `PLATEGA_MERCHANT_ID` и `PLATEGA_SECRET`.
-- `PLATEGA_CRYPTO_ENABLED` - отдельная crypto-кнопка Platega;
+2. Включите необходимые кнопки `PLATEGA_SBP_ENABLED`, `PLATEGA_CRYPTO_ENABLED`.
-- `PLATEGA_PAYMENT_METHOD` - устаревший/резервный ID метода оплаты для старых callback-запросов и старых установок.
+4. Скопируйте URL вебхука из админ-панели и укажите его в кабинете Platega.
 
-Что настроить:
+### Справочник
 
-1. Укажите `PLATEGA_BASE_URL`, `PLATEGA_MERCHANT_ID` и `PLATEGA_SECRET`.
+- [Platega](../configuration/env-vars.md#platega)
-2. Заполните `PLATEGA_SBP_METHOD` и/или `PLATEGA_CRYPTO_METHOD`, если используете отдельные кнопки.
-3. Проверьте `PLATEGA_RETURN_URL` и `PLATEGA_FAILED_URL`.
-4. Укажите URL вебхука: `WEBHOOK_BASE_URL` + `/webhook/platega`.
-5. Настройте тексты и иконки кнопок через `PAYMENT_PLATEGA_SBP_*` и `PAYMENT_PLATEGA_CRYPTO_*`.
-6. Добавьте нужные методы в `PAYMENT_METHODS_ORDER`.
-
-Справочник переменных: [Platega](../configuration/env-vars.md#platega).
 
 ## SeverPay
 
 SeverPay подключается как отдельный платежный метод с собственным MID, token и сроком жизни платежной ссылки.
 
-Что настроить:
+### Настройка
 
 1. Включите `SEVERPAY_ENABLED`.
 2. Укажите `SEVERPAY_BASE_URL`.
 3. Заполните `SEVERPAY_MID` и `SEVERPAY_TOKEN`.
-4. Настройте `SEVERPAY_RETURN_URL`.
+4. Скопируйте URL вебхука из админ-панели и укажите его в кабинете SeverPay.
-5. Укажите URL вебхука: `WEBHOOK_BASE_URL` + `/webhook/severpay`.
+5. При необходимости задайте `SEVERPAY_LIFETIME_MINUTES`.
-6. При необходимости задайте `SEVERPAY_LIFETIME_MINUTES`.
-7. Добавьте `severpay` в `PAYMENT_METHODS_ORDER`.
 
-Справочник переменных: [SeverPay](../configuration/env-vars.md#severpay).
+### Справочник
+
+- [SeverPay](../configuration/env-vars.md#severpay)
 
 ## Wata
 
 Wata подключается как отдельный провайдер с bearer token, платежными ссылками и опциональной проверкой подписи webhook.
 
-Что настроить:
+### Настройка
 
 1. Включите `WATA_ENABLED`.
 2. Укажите `WATA_BASE_URL` и `WATA_API_TOKEN`.
-3. Проверьте `WATA_RETURN_URL` и `WATA_FAILED_URL`.
+3. Настройте `WATA_LINK_TTL_MINUTES`.
-4. Настройте `WATA_LINK_TTL_MINUTES`: минимум 15 минут, максимум 43200.
+4. Скопируйте URL вебхука из админ-панели и укажите его в кабинете Wata.
-5. Укажите URL вебхука: `WEBHOOK_BASE_URL` + `/webhook/wata`.
+5. При необходимости включите `WATA_WEBHOOK_VERIFY_SIGNATURE`.
-6. Если включаете проверку подписи, задайте `WATA_WEBHOOK_VERIFY_SIGNATURE` и при необходимости `WATA_PUBLIC_KEY`.
+6. Если используется проверка подписи, задайте `WATA_PUBLIC_KEY`.
-7. Для дополнительной защиты заполните `WATA_TRUSTED_IPS`.
+7. Для IP-фильтрации заполните `WATA_TRUSTED_IPS`.
-8. Добавьте `wata` в `PAYMENT_METHODS_ORDER`.
 
-Справочник переменных: [Wata](../configuration/env-vars.md#wata).
+### Ограничения
+
+- `WATA_LINK_TTL_MINUTES` должен быть от `15` до `43200`.
+
+### Справочник
+
+- [Wata](../configuration/env-vars.md#wata)
 
 ## CryptoPay
 
 CryptoPay используется для криптовалютных платежей через отдельный токен и сеть Crypto Bot API.
 
-Что настроить:
+### Настройка
 
 1. Включите `CRYPTOPAY_ENABLED`.
 2. Укажите `CRYPTOPAY_TOKEN`.
 3. Выберите `CRYPTOPAY_NETWORK`: `mainnet` или `testnet`.
 4. Задайте `CRYPTOPAY_CURRENCY_TYPE`: `fiat` или `crypto`.
 5. Проверьте `CRYPTOPAY_ASSET`, например `RUB`, `USDT` или `BTC`.
-6. Укажите URL вебхука: `WEBHOOK_BASE_URL` + `/webhook/cryptopay`.
+6. Скопируйте URL вебхука из админ-панели и укажите его в CryptoPay.
-7. Добавьте `cryptopay` в `PAYMENT_METHODS_ORDER`.
 
-Для тестов используйте соответствующую сеть: testnet-токен не должен попадать в mainnet-настройки. Если сумма или asset выглядят неверно, проверьте сочетание `CRYPTOPAY_CURRENCY_TYPE` и `CRYPTOPAY_ASSET`.
+### Проверка
 
-Справочник переменных: [CryptoPay](../configuration/env-vars.md#cryptopay).
+- Testnet-токен должен использоваться только с `testnet`.
+- Mainnet-токен должен использоваться только с `mainnet`.
+- Если сумма или asset выглядят неверно, проверьте сочетание `CRYPTOPAY_CURRENCY_TYPE` и `CRYPTOPAY_ASSET`.
+
+### Справочник
+
+- [CryptoPay](../configuration/env-vars.md#cryptopay)
 
 ## Heleket
 
-Heleket используется для крипто-инвойсов с отдельными merchant ID, ключом платежного API, валютой инвойса и настройками проверки webhook.
+Heleket используется для крипто-инвойсов с merchant ID, ключом платежного API, валютой инвойса и настройками проверки webhook.
 
-Что настроить:
+### Настройка
 
 1. Включите `HELEKET_ENABLED`.
 2. Укажите `HELEKET_BASE_URL`, `HELEKET_MERCHANT_ID` и `HELEKET_API_KEY`.
 3. Настройте `HELEKET_CURRENCY`.
 4. При необходимости задайте `HELEKET_TO_CURRENCY` и `HELEKET_NETWORK`.
 5. Проверьте `HELEKET_RETURN_URL` и `HELEKET_SUCCESS_URL`.
-6. Настройте `HELEKET_LIFETIME_SECONDS`: допустимый диапазон 300..43200.
+6. Настройте `HELEKET_LIFETIME_SECONDS`.
-7. Укажите URL вебхука: `WEBHOOK_BASE_URL` + `/webhook/heleket`.
+7. Скопируйте URL вебхука из админ-панели и укажите его в кабинете Heleket.
-8. Если включаете проверку webhook, задайте `HELEKET_VERIFY_WEBHOOK_SIGNATURE`.
+8. При необходимости включите `HELEKET_VERIFY_WEBHOOK_SIGNATURE`.
 9. Для IP-фильтрации заполните `HELEKET_TRUSTED_IPS`.
-10. Добавьте `heleket` в `PAYMENT_METHODS_ORDER`.
 
-Справочник переменных: [Heleket](../configuration/env-vars.md#heleket).
+### Ограничения
+
+- `HELEKET_LIFETIME_SECONDS` должен быть от `300` до `43200`.
+
+### Справочник
+
+- [Heleket](../configuration/env-vars.md#heleket)
 
 ## PayKilla
 
-PayKilla используется для крипто-инвойсов V2 через hosted checkout `https://gopay.paykilla.com/{invoice_id}`. API-запросы подписываются HMAC-SHA256, webhook проверяется по заголовку `X-API-SIGN` и raw body.
+PayKilla используется для крипто-инвойсов V2 через hosted checkout `https://gopay.paykilla.com/{invoice_id}`.
 
-PayKilla строго валидирует текстовые поля invoice. Поэтому Minishop отправляет в `purpose` и `description` простой английский текст `<WEBAPP_TITLE> payment <id>`, а локализованное описание платежа оставляет только внутри Minishop. Дополнительно эти поля проходят ASCII-safe sanitizer: допускаются ASCII-буквы, цифры, пробелы, `_`, `.`, `,`.
+API-запросы подписываются HMAC-SHA256. Webhook проверяется по заголовку `X-API-SIGN` и raw body.
 
-Minishop создает invoice в валюте, которую PayKilla принимает в поле `currency`. Если валюта тарифа входит в `PAYKILLA_INVOICE_CURRENCIES`, сумма отправляется как есть. Если валюта тарифа не входит в этот список, сумма конвертируется в `PAYKILLA_CURRENCY`; по умолчанию рублевые тарифы конвертируются в `USD` через no-key endpoint ExchangeRate-API `https://open.er-api.com/v6/latest/{source}` с кэшем `PAYKILLA_EXCHANGE_RATE_CACHE_SECONDS`. Перед созданием invoice Minishop читает `GET /api/v2/currency` и проверяет `invoiceMin`/`invoiceMax` для валюты инвойса.
+### Особенности
 
-Минимальная сумма платежа задается настройками `PAYKILLA_MIN_PAYMENT_AMOUNT` и `PAYKILLA_MIN_PAYMENT_CURRENCY`; по умолчанию это `10 USD`. Если выбранный тариф/пакет ниже этого порога после конвертации, Telegram bot не показывает кнопку PayKilla, WebApp показывает метод неактивным, а API создания платежа возвращает ошибку `payment_amount_below_minimum`.
+- PayKilla строго валидирует текстовые поля invoice.
+- В `purpose` и `description` Minishop отправляет простой английский текст `<WEBAPP_TITLE> payment <id>`.
+- Локализованное описание платежа остается только внутри Minishop.
+- ASCII-safe sanitizer допускает ASCII-буквы, цифры, пробелы, `_`, `.`, `,`.
+- Минимальная сумма платежа задается настройками `PAYKILLA_MIN_PAYMENT_AMOUNT` и `PAYKILLA_MIN_PAYMENT_CURRENCY`; по умолчанию это `10 USD`.
+- Если выбранный тариф/пакет ниже этого порога после конвертации, Telegram bot не показывает кнопку PayKilla, WebApp показывает метод неактивным, а API создания платежа возвращает ошибку `payment_amount_below_minimum`.
 
-Payload создания invoice содержит обязательные поля `type`, `purpose`, `currency`, `totalPrice`, `paymentCurrencies`, служебный `clientOrderId`, а также полезные optional поля `description`, `expiredAt`, `userPaysServiceFee`, `userPaysNetworkFee`. Redirect URLs в PayKilla не отправляются; завершение платежа обрабатывается через webhook.
+### Валюта invoice
 
-Какие полномочия нужны API key:
+Minishop создает invoice в валюте, которую PayKilla принимает в поле `currency`.
+
+Если валюта тарифа входит в `PAYKILLA_INVOICE_CURRENCIES`, сумма отправляется как есть.
+
+Если валюта тарифа не входит в список, сумма конвертируется в `PAYKILLA_CURRENCY`. По умолчанию рублевые тарифы конвертируются в `USD` через ExchangeRate-API с кэшем `PAYKILLA_EXCHANGE_RATE_CACHE_SECONDS`.
+
+Перед созданием invoice Minishop читает `GET /api/v2/currency` и проверяет `invoiceMin`/`invoiceMax` для валюты инвойса. Этот endpoint также показывает актуальные currency/payment-method ограничения конкретного merchant account.
+
+### Payload invoice
+
+Payload создания invoice содержит обязательные поля `type`, `purpose`, `currency`, `totalPrice` и `paymentCurrencies`.
+
+Дополнительно отправляются `clientOrderId`, `description`, `expiredAt`, `userPaysServiceFee` и `userPaysNetworkFee`.
+
+Redirect URLs в PayKilla не отправляются. Завершение платежа обрабатывается через webhook.
+
+### API key
 
 1. В PayKilla Dashboard откройте **Settings -> API keys**.
 2. Создайте ключ типа **HMAC**.
 3. Для приема оплат включите permission **INVOICE**.
-4. Permission **WITHDRAWAL** не нужен для Minishop-платежей; не включайте его без отдельной необходимости выплат.
+4. Permission **WITHDRAWAL** не нужен для Minishop-платежей.
-5. Сохраните `publicKey` в `PAYKILLA_API_KEY`, а `secretKey` в `PAYKILLA_SECRET_KEY`.
+5. Сохраните `publicKey` в `PAYKILLA_API_KEY`.
+6. Сохраните `secretKey` в `PAYKILLA_SECRET_KEY`.
 
-Как настроить webhook в PayKilla:
+### Webhook
 
-1. Откройте **Settings -> Webhooks**.
+1. В PayKilla Dashboard откройте **Settings -> Webhooks**.
-2. В URL укажите `WEBHOOK_BASE_URL` + `/webhook/paykilla`, например `https://bot.example.com/webhook/paykilla`.
+2. Скопируйте URL вебхука из админ-панели и укажите его в PayKilla.
-3. Минимальные галочки: `INVOICE_PAID`, `INVOICE_EXPIRED`.
+3. Включите минимальные события: `INVOICE_PAID`, `INVOICE_EXPIRED`.
-4. Рекомендуемые галочки для production: `INVOICE_PAID`, `PAYMENT_COMPLETED`, `PAYMENT_FAILED`, `PAYMENT_OVERPAID`, `PAYMENT_UNDERPAID`, `PAYMENT_PARTIAL`, `INVOICE_EXPIRED`, `COMPLIANCE_FAILED`.
+4. Для production также включите `PAYMENT_COMPLETED`, `PAYMENT_FAILED`, `PAYMENT_OVERPAID`, `PAYMENT_UNDERPAID`, `PAYMENT_PARTIAL`, `COMPLIANCE_FAILED`.
-5. Опционально включите `INVOICE_CREATED`, `PAYMENT_PENDING`, `TRANSACTION_CONFIRMED` и `TRANSACTION_FINAL`, если нужны промежуточные события в логах.
+5. Если нужны промежуточные статусы в логах, дополнительно включите `INVOICE_CREATED`, `PAYMENT_PENDING`, `TRANSACTION_CONFIRMED` и `TRANSACTION_FINAL`.
-6. Оставьте `PAYKILLA_VERIFY_WEBHOOK_SIGNATURE=True`. Если публичный URL у PayKilla отличается от `WEBHOOK_BASE_URL` + `/webhook/paykilla`, задайте точное значение в `PAYKILLA_WEBHOOK_URL`.
+6. Оставьте `PAYKILLA_VERIFY_WEBHOOK_SIGNATURE=True`.
 
-Что настроить в Minishop:
+### Настройка
 
 1. Включите `PAYKILLA_ENABLED`.
 2. Укажите `PAYKILLA_API_KEY` и `PAYKILLA_SECRET_KEY`.
 3. Оставьте `PAYKILLA_CURRENCY=USD`, если PayKilla не принимает валюту тарифов как invoice currency. В `PAYKILLA_INVOICE_CURRENCIES` укажите валюты, доступные в PayKilla для поля `currency`, например `USD,EUR`.
-4. В `PAYKILLA_PAYMENT_CURRENCIES` оставьте `USDTTRC,BTC,ETH,USDTBSC,USDTTON` или укажите другой список тикеров, доступных в PayKilla Dashboard.
+4. В `PAYKILLA_PAYMENT_CURRENCIES` оставьте `USDTTRC,BTC,ETH,USDTBSC,USDTTON` или укажите другой список тикеров, доступных в PayKilla Dashboard; `USDTTRC` должен идти первым.
 5. Оставьте `PAYKILLA_MIN_PAYMENT_AMOUNT=10` и `PAYKILLA_MIN_PAYMENT_CURRENCY=USD`, если минимальный invoice PayKilla равен `10 USD`.
 6. Убедитесь, что webhook `/webhook/paykilla` настроен в PayKilla: Minishop не отправляет redirect URLs в PayKilla и полагается на webhook для активации платежа.
 7. Добавьте `paykilla` в `PAYMENT_METHODS_ORDER`, если хотите задать явный порядок кнопок.
 
-Справочник переменных: [PayKilla](../configuration/env-vars.md#paykilla).
+### Справочник
+
+- [PayKilla](../configuration/env-vars.md#paykilla)
 
 ## Telegram Stars
 
 Telegram Stars используются напрямую и поддерживаются в legacy-ценах и JSON-каталоге тарифов.
 
-Где применяются Stars:
+### Где используются
 
-- цены периодов подписки;
+- Цены period-подписок.
-- пакеты трафика;
+- Пакеты трафика.
-- premium-докупки;
+- Premium-докупки.
 - HWID-докупки, если они включены в каталоге тарифов.
 
-Что проверить:
+### Настройка
 
-- `STARS_ENABLED`;
+1. Включите `STARS_ENABLED`.
-- отдельный платежный webhook не настраивается: Telegram Stars приходят через webhook Telegram-бота `WEBHOOK_BASE_URL` + `/tg/webhook`;
+2. Проверьте Stars-цены в legacy-настройках или JSON-каталоге.
-- Stars-цены в legacy-настройках или JSON-каталоге;
+3. Убедитесь, что цена округляется до целого количества Stars.
-- корректное округление цены до целого количества Stars;
+4. Проверьте сценарии смены тарифа.
-- сценарии смены тарифа: XTR/Stars-докупки не конвертируются без явного курса.
 
-См. также [переменные платежей](../configuration/env-vars.md#платежи) и [тарифы](tariffs.md).
+### Ограничения
+
+- Отдельный платежный webhook не нужен.
+- Stars-события приходят через webhook Telegram-бота: `WEBHOOK_BASE_URL` + `/tg/webhook`.
+- XTR/Stars-докупки не конвертируются без явно заданного курса.
+
+### Справочник
+
+- [Переменные платежей](../configuration/env-vars.md#платежи)
+- [Тарифы](tariffs.md)