docs: refactor docs structure

2026-05-26 17:26:46 +03:00
parent 804ccdabec
commit 0c167c8f09
54 changed files with 1154 additions and 351 deletions
@@ -0,0 +1,28 @@
+# CryptoPay
+
+CryptoPay используется для криптовалютных платежей через отдельный токен и сеть Crypto Bot API.
+
+## Что включить
+
+- `CRYPTOPAY_ENABLED` - включает CryptoPay среди доступных методов.
+- Presentation-ключи `PAYMENT_CRYPTOPAY_*` - подписи и иконки кнопки в Mini App и Telegram.
+
+## Что настроить
+
+1. Укажите `CRYPTOPAY_TOKEN`.
+2. Выберите `CRYPTOPAY_NETWORK`: `mainnet` или `testnet`.
+3. Задайте `CRYPTOPAY_CURRENCY_TYPE`: `fiat` или `crypto`.
+4. Проверьте `CRYPTOPAY_ASSET`, например `RUB`, `USDT` или `BTC`.
+5. Добавьте `cryptopay` в `PAYMENT_METHODS_ORDER`.
+
+## Проверка
+
+- Для тестов используйте соответствующую сеть: testnet-токен не должен попадать в mainnet-настройки.
+- Выполните тестовый платеж и проверьте, что статус закрывается после callback от провайдера.
+- Если сумма или asset выглядят неверно, проверьте сочетание `CRYPTOPAY_CURRENCY_TYPE` и `CRYPTOPAY_ASSET`.
+
+## Где подробнее
+
+- [Переменные CryptoPay](../configuration/env-vars.md#cryptopay)
+- [Настройка платежей](../features/payments.md)
+- [Логи и диагностика](../troubleshooting/logs.md)
@@ -0,0 +1,16 @@
+# FreeKassa
+
+FreeKassa подключается как отдельный платежный метод и обрабатывает входящие webhook-события через backend.
+
+## Что настроить
+
+- Включение провайдера: `FREEKASSA_ENABLED`.
+- ID магазина, API/secret-ключи и настройки подписи.
+- Trusted IP allowlist, если используется.
+- Публичный webhook URL на `WEBHOOK_BASE_URL`.
+
+## Где подробнее
+
+- [Переменные FreeKassa](../configuration/env-vars.md#freekassa)
+- [Платежи](../features/payments.md)
+- [Логи и проверка](../troubleshooting/logs.md)
@@ -0,0 +1,31 @@
+# Heleket
+
+Heleket используется для crypto-инвойсов с отдельными merchant ID, payment API key, валютой инвойса и настройками webhook-проверки.
+
+## Что включить
+
+- `HELEKET_ENABLED` - включает Heleket среди доступных методов.
+- Presentation-ключи `PAYMENT_HELEKET_*` - подписи и иконки кнопки.
+
+## Что настроить
+
+1. Укажите `HELEKET_BASE_URL`, `HELEKET_MERCHANT_ID` и `HELEKET_API_KEY`.
+2. Настройте `HELEKET_CURRENCY`.
+3. При необходимости задайте `HELEKET_TO_CURRENCY` и `HELEKET_NETWORK`.
+4. Проверьте `HELEKET_RETURN_URL` и `HELEKET_SUCCESS_URL`.
+5. Настройте `HELEKET_LIFETIME_SECONDS`: допустимый диапазон 300..43200.
+6. Если включаете проверку webhook, задайте `HELEKET_VERIFY_WEBHOOK_SIGNATURE`.
+7. Для IP-фильтрации заполните `HELEKET_TRUSTED_IPS`.
+8. Добавьте `heleket` в `PAYMENT_METHODS_ORDER`.
+
+## Проверка
+
+- Создайте тестовый инвойс и убедитесь, что пользователь получает корректную ссылку.
+- Проверьте, что сеть и валюта соответствуют настройкам в кабинете Heleket.
+- Если webhook отклоняется, проверьте подпись, allowlist и фактический payload в backend-логах.
+
+## Где подробнее
+
+- [Переменные Heleket](../configuration/env-vars.md#heleket)
+- [Настройка платежей](../features/payments.md)
+- [Логи и диагностика](../troubleshooting/logs.md)
@@ -0,0 +1,30 @@
+# Platega
+
+Platega подключается как отдельный платежный провайдер, но внутри Minishop может дать несколько кнопок: основную legacy-кнопку, СБП/карту и крипто-кнопку. Общие merchant-параметры задаются один раз, а method ID и подписи кнопок настраиваются отдельно.
+
+## Что включить
+
+- `PLATEGA_ENABLED` - общий флаг провайдера.
+- `PLATEGA_SBP_ENABLED` - отдельная кнопка СБП/карта.
+- `PLATEGA_CRYPTO_ENABLED` - отдельная crypto-кнопка Platega.
+- `PLATEGA_PAYMENT_METHOD` - legacy/fallback method ID для старых callback и старых установок.
+
+## Что настроить
+
+1. Укажите `PLATEGA_BASE_URL`, `PLATEGA_MERCHANT_ID` и `PLATEGA_SECRET`.
+2. Заполните `PLATEGA_SBP_METHOD` и/или `PLATEGA_CRYPTO_METHOD`, если используете отдельные кнопки.
+3. Проверьте `PLATEGA_RETURN_URL` и `PLATEGA_FAILED_URL`.
+4. Настройте тексты и иконки кнопок через `PAYMENT_PLATEGA_SBP_*` и `PAYMENT_PLATEGA_CRYPTO_*`.
+5. Добавьте нужные методы в `PAYMENT_METHODS_ORDER`.
+
+## Проверка
+
+- После сохранения настроек откройте Mini App и убедитесь, что видны только включенные Platega-кнопки.
+- Выполните тестовую оплату для каждой включенной кнопки: СБП/карта и crypto используют разные method ID.
+- При ошибках проверьте backend-логи и ответ провайдера при создании платежной ссылки.
+
+## Где подробнее
+
+- [Переменные Platega](../configuration/env-vars.md#platega)
+- [Настройка платежей](../features/payments.md)
+- [Логи и диагностика](../troubleshooting/logs.md)
@@ -0,0 +1,28 @@
+# SeverPay
+
+SeverPay подключается как отдельный платежный метод с собственным MID, token и сроком жизни платежной ссылки.
+
+## Что включить
+
+- `SEVERPAY_ENABLED` - показывает SeverPay среди доступных методов оплаты.
+- Presentation-ключи `PAYMENT_SEVERPAY_*` - подписи и иконки кнопки в Mini App и Telegram.
+
+## Что настроить
+
+1. Укажите `SEVERPAY_BASE_URL`.
+2. Заполните `SEVERPAY_MID` и `SEVERPAY_TOKEN`.
+3. Настройте `SEVERPAY_RETURN_URL`.
+4. При необходимости задайте `SEVERPAY_LIFETIME_MINUTES`.
+5. Добавьте `severpay` в `PAYMENT_METHODS_ORDER`.
+
+## Проверка
+
+- Создайте тестовый платеж и проверьте, что пользователь получает платежную ссылку.
+- Убедитесь, что ссылка живет ожидаемое время, если задан `SEVERPAY_LIFETIME_MINUTES`.
+- После оплаты проверьте статус платежа в backend-логах и в админке.
+
+## Где подробнее
+
+- [Переменные SeverPay](../configuration/env-vars.md#severpay)
+- [Настройка платежей](../features/payments.md)
+- [Логи и диагностика](../troubleshooting/logs.md)
@@ -0,0 +1,19 @@
+# Telegram Stars
+
+Telegram Stars используются напрямую и поддерживаются в legacy-ценах и JSON-каталоге тарифов.
+
+## Где применяются Stars
+
+- Цены периодов подписки.
+- Пакеты трафика.
+- Premium-докупки.
+- HWID-докупки, если они включены в каталоге тарифов.
+
+## Что проверить
+
+- `STARS_ENABLED`.
+- Stars-цены в legacy-настройках или JSON-каталоге.
+- Корректное округление цены до целого количества Stars.
+- Сценарии смены тарифа: XTR/Stars-докупки не конвертируются без явного курса.
+
+Подробности: [переменные платежей](../configuration/env-vars.md#платежи) и [тарифы](../features/tariffs.md).
@@ -0,0 +1,30 @@
+# Wata
+
+Wata подключается как отдельный провайдер с bearer token, платежными ссылками и опциональной проверкой подписи webhook.
+
+## Что включить
+
+- `WATA_ENABLED` - включает Wata для пользователей.
+- `WATA_ADMIN_ONLY_ENABLED` - оставляет метод доступным только для админских сценариев, если используется вместо публичного включения.
+- Presentation-ключи `PAYMENT_WATA_*` - подписи и иконки кнопки.
+
+## Что настроить
+
+1. Укажите `WATA_BASE_URL` и `WATA_API_TOKEN`.
+2. Проверьте `WATA_RETURN_URL` и `WATA_FAILED_URL`.
+3. Настройте `WATA_LINK_TTL_MINUTES`: минимум 15 минут, максимум 43200.
+4. Если включаете проверку подписи, задайте `WATA_WEBHOOK_VERIFY_SIGNATURE` и при необходимости `WATA_PUBLIC_KEY`.
+5. Для дополнительной защиты заполните `WATA_TRUSTED_IPS`.
+6. Добавьте `wata` в `PAYMENT_METHODS_ORDER`.
+
+## Проверка
+
+- Создайте тестовый платеж и убедитесь, что ссылка открывается у пользователя.
+- Проверьте входящий webhook: подпись и IP-allowlist должны соответствовать фактическому запросу Wata.
+- Если платеж остается в pending, проверьте backend-логи вокруг webhook и статуса ссылки.
+
+## Где подробнее
+
+- [Переменные Wata](../configuration/env-vars.md#wata)
+- [Настройка платежей](../features/payments.md)
+- [Логи и диагностика](../troubleshooting/logs.md)
@@ -0,0 +1,16 @@
+# YooKassa
+
+YooKassa используется для рублевых оплат и может участвовать в сценариях автопродления period-подписок.
+
+## Что настроить
+
+- Включение провайдера: `YOOKASSA_ENABLED`.
+- Идентификаторы и секреты магазина.
+- Webhook URL на backend-домен.
+- Отображение кнопки оплаты и порядок платежных методов.
+
+## Где подробнее
+
+- [Переменные YooKassa](../configuration/env-vars.md#yookassa)
+- [Платежи](../features/payments.md)
+- [Тарифы и автопродление](../features/tariffs.md#автопродление-пробный-период-и-бонусы)