diff --git a/backend/bot/payment_providers/freekassa.py b/backend/bot/payment_providers/freekassa.py index 1d830a5..9be3bd0 100644 --- a/backend/bot/payment_providers/freekassa.py +++ b/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", ), diff --git a/docs/features/payments.md b/docs/features/payments.md index 194a402..45c85bb 100644 --- a/docs/features/payments.md +++ b/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 и сценарии покупки. -- [Логи](../troubleshooting/logs.md) помогают проверить webhook и создание платежных ссылок. +## Общие ссылки + +- [Справочник `.env`](../configuration/env-vars.md) — все ключи платежных провайдеров. +- [Админ-панель](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`; -- идентификаторы и секреты магазина; -- URL вебхука: `WEBHOOK_BASE_URL` + `/webhook/yookassa`; -- отображение кнопки оплаты и порядок платежных методов. +1. Включите `YOOKASSA_ENABLED`. +2. Заполните `YOOKASSA_SHOP_ID`, `YOOKASSA_SECRET_KEY` и `YOOKASSA_RETURN_URL`. +3. Скопируйте URL вебхука из админ-панели и укажите его в кабинете YooKassa. -Справочник переменных: [YooKassa](../configuration/env-vars.md#yookassa). +### Справочник + +- [YooKassa](../configuration/env-vars.md#yookassa) ## FreeKassa -FreeKassa подключается как отдельный платежный метод и обрабатывает входящие webhook-события через `backend`. +FreeKassa подключается как отдельный платежный метод. Входящие webhook-события обрабатываются через `backend`. -Что настроить: +### Настройка -- включение провайдера: `FREEKASSA_ENABLED`; -- ID магазина, API/secret-ключи и настройки подписи; -- список доверенных IP, если используется; -- публичный URL вебхука: `WEBHOOK_BASE_URL` + `/webhook/freekassa`. +1. Включите `FREEKASSA_ENABLED`. +2. Заполните `FREEKASSA_MERCHANT_ID`, `FREEKASSA_FIRST_SECRET`, `FREEKASSA_SECOND_SECRET` и `FREEKASSA_API_KEY`. +3. Проверьте настройки подписи. +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` - общий флаг провайдера; -- `PLATEGA_SBP_ENABLED` - отдельная кнопка СБП/карта; -- `PLATEGA_CRYPTO_ENABLED` - отдельная crypto-кнопка Platega; -- `PLATEGA_PAYMENT_METHOD` - устаревший/резервный ID метода оплаты для старых callback-запросов и старых установок. +1. Включите `PLATEGA_ENABLED`. +3. Укажите `PLATEGA_MERCHANT_ID` и `PLATEGA_SECRET`. +2. Включите необходимые кнопки `PLATEGA_SBP_ENABLED`, `PLATEGA_CRYPTO_ENABLED`. +4. Скопируйте URL вебхука из админ-панели и укажите его в кабинете Platega. -Что настроить: +### Справочник -1. Укажите `PLATEGA_BASE_URL`, `PLATEGA_MERCHANT_ID` и `PLATEGA_SECRET`. -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). +- [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`. -5. Укажите URL вебхука: `WEBHOOK_BASE_URL` + `/webhook/severpay`. -6. При необходимости задайте `SEVERPAY_LIFETIME_MINUTES`. -7. Добавьте `severpay` в `PAYMENT_METHODS_ORDER`. +4. Скопируйте URL вебхука из админ-панели и укажите его в кабинете SeverPay. +5. При необходимости задайте `SEVERPAY_LIFETIME_MINUTES`. -Справочник переменных: [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`. -4. Настройте `WATA_LINK_TTL_MINUTES`: минимум 15 минут, максимум 43200. -5. Укажите URL вебхука: `WEBHOOK_BASE_URL` + `/webhook/wata`. -6. Если включаете проверку подписи, задайте `WATA_WEBHOOK_VERIFY_SIGNATURE` и при необходимости `WATA_PUBLIC_KEY`. -7. Для дополнительной защиты заполните `WATA_TRUSTED_IPS`. -8. Добавьте `wata` в `PAYMENT_METHODS_ORDER`. +3. Настройте `WATA_LINK_TTL_MINUTES`. +4. Скопируйте URL вебхука из админ-панели и укажите его в кабинете Wata. +5. При необходимости включите `WATA_WEBHOOK_VERIFY_SIGNATURE`. +6. Если используется проверка подписи, задайте `WATA_PUBLIC_KEY`. +7. Для IP-фильтрации заполните `WATA_TRUSTED_IPS`. -Справочник переменных: [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`. -7. Добавьте `cryptopay` в `PAYMENT_METHODS_ORDER`. +6. Скопируйте URL вебхука из админ-панели и укажите его в CryptoPay. -Для тестов используйте соответствующую сеть: 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. -7. Укажите URL вебхука: `WEBHOOK_BASE_URL` + `/webhook/heleket`. -8. Если включаете проверку webhook, задайте `HELEKET_VERIFY_WEBHOOK_SIGNATURE`. +6. Настройте `HELEKET_LIFETIME_SECONDS`. +7. Скопируйте URL вебхука из админ-панели и укажите его в кабинете Heleket. +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` простой английский текст ` payment `, а локализованное описание платежа оставляет только внутри 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 отправляет простой английский текст ` payment `. +- Локализованное описание платежа остается только внутри 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-платежей; не включайте его без отдельной необходимости выплат. -5. Сохраните `publicKey` в `PAYKILLA_API_KEY`, а `secretKey` в `PAYKILLA_SECRET_KEY`. +4. Permission **WITHDRAWAL** не нужен для Minishop-платежей. +5. Сохраните `publicKey` в `PAYKILLA_API_KEY`. +6. Сохраните `secretKey` в `PAYKILLA_SECRET_KEY`. -Как настроить webhook в PayKilla: +### Webhook -1. Откройте **Settings -> Webhooks**. -2. В URL укажите `WEBHOOK_BASE_URL` + `/webhook/paykilla`, например `https://bot.example.com/webhook/paykilla`. -3. Минимальные галочки: `INVOICE_PAID`, `INVOICE_EXPIRED`. -4. Рекомендуемые галочки для production: `INVOICE_PAID`, `PAYMENT_COMPLETED`, `PAYMENT_FAILED`, `PAYMENT_OVERPAID`, `PAYMENT_UNDERPAID`, `PAYMENT_PARTIAL`, `INVOICE_EXPIRED`, `COMPLIANCE_FAILED`. -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`. +1. В PayKilla Dashboard откройте **Settings -> Webhooks**. +2. Скопируйте URL вебхука из админ-панели и укажите его в PayKilla. +3. Включите минимальные события: `INVOICE_PAID`, `INVOICE_EXPIRED`. +4. Для production также включите `PAYMENT_COMPLETED`, `PAYMENT_FAILED`, `PAYMENT_OVERPAID`, `PAYMENT_UNDERPAID`, `PAYMENT_PARTIAL`, `COMPLIANCE_FAILED`. +5. Если нужны промежуточные статусы в логах, дополнительно включите `INVOICE_CREATED`, `PAYMENT_PENDING`, `TRANSACTION_CONFIRMED` и `TRANSACTION_FINAL`. +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: +### Где используются -- цены периодов подписки; -- пакеты трафика; -- premium-докупки; +- Цены period-подписок. +- Пакеты трафика. +- Premium-докупки. - HWID-докупки, если они включены в каталоге тарифов. -Что проверить: +### Настройка -- `STARS_ENABLED`; -- отдельный платежный webhook не настраивается: Telegram Stars приходят через webhook Telegram-бота `WEBHOOK_BASE_URL` + `/tg/webhook`; -- Stars-цены в legacy-настройках или JSON-каталоге; -- корректное округление цены до целого количества Stars; -- сценарии смены тарифа: XTR/Stars-докупки не конвертируются без явного курса. +1. Включите `STARS_ENABLED`. +2. Проверьте Stars-цены в legacy-настройках или JSON-каталоге. +3. Убедитесь, что цена округляется до целого количества Stars. +4. Проверьте сценарии смены тарифа. -См. также [переменные платежей](../configuration/env-vars.md#платежи) и [тарифы](tariffs.md). +### Ограничения + +- Отдельный платежный webhook не нужен. +- Stars-события приходят через webhook Telegram-бота: `WEBHOOK_BASE_URL` + `/tg/webhook`. +- XTR/Stars-докупки не конвертируются без явно заданного курса. + +### Справочник + +- [Переменные платежей](../configuration/env-vars.md#платежи) +- [Тарифы](tariffs.md)