remnawave-minishop/docs/features/payments.md

Платежи

Платежные методы включаются через .env или админ-панель, если параметр добавлен в allowlist настроек. В Mini App и Telegram-сценариях включённые методы отображаются как кнопки оплаты.

Общий порядок настройки

1. Включите нужный провайдер.
2. Заполните публичные параметры, секреты и URL возврата.
3. Настройте webhook URL у провайдера, если он используется.
4. Проверьте порядок методов в PAYMENT_METHODS_ORDER.
5. Проверьте подписи и иконки кнопок оплаты.
6. Выполните тестовый платеж.
7. Проверьте логи backend.

Note

Если URL возврата не задан явно, используется ссылка на Telegram-бота.

Общие ссылки

• Справочник .env — все ключи платежных провайдеров.
• Админ-панель — UI-настройки платежей.
• Тарифы — цены, Telegram Stars и сценарии покупки.
• Логи — проверка 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 + путь из таблицы.

Провайдер	Что указать в кабинете провайдера	Комментарий
YooKassa	WEBHOOK_BASE_URL + /webhook/yookassa	Например https://bot.example.com/webhook/yookassa.
FreeKassa	WEBHOOK_BASE_URL + /webhook/freekassa	Используйте как notification/webhook URL; при IP-фильтрации заполните FREEKASSA_TRUSTED_IPS.
Platega	WEBHOOK_BASE_URL + /webhook/platega	Один общий webhook для основной, СБП/карты и crypto-кнопки Platega.
SeverPay	WEBHOOK_BASE_URL + /webhook/severpay	Укажите как callback/webhook URL, если поле есть в кабинете мерчанта.
Wata	WEBHOOK_BASE_URL + /webhook/wata	Если включена проверка подписи, настройте WATA_WEBHOOK_VERIFY_SIGNATURE и WATA_PUBLIC_KEY.
CryptoPay	WEBHOOK_BASE_URL + /webhook/cryptopay	Указывается в настройках Crypto Bot / CryptoPay webhook.
Heleket	WEBHOOK_BASE_URL + /webhook/heleket	При необходимости включите HELEKET_VERIFY_WEBHOOK_SIGNATURE и HELEKET_TRUSTED_IPS.
PayKilla	WEBHOOK_BASE_URL + /webhook/paykilla	Указывается в PayKilla Dashboard -> Settings -> Webhooks; включите события оплаты инвойсов.
Telegram Stars	Отдельный платежный webhook не нужен	Stars-события приходят через webhook Telegram-бота: WEBHOOK_BASE_URL + /tg/webhook.

После настройки сделайте тестовый платеж и проверьте, что в логах backend видно входящий POST на нужный путь. Если провайдер сообщает, что адрес недоступен, сначала проверьте DNS/HTTPS и reverse proxy для WEBHOOK_BASE_URL, затем убедитесь, что путь начинается ровно с /webhook/... без /api, /auth и frontend-домена.

YooKassa

YooKassa используется для рублевых оплат. Провайдер также может участвовать в сценариях автопродления period-подписок.

Настройка

1. Включите YOOKASSA_ENABLED.
2. Заполните YOOKASSA_SHOP_ID, YOOKASSA_SECRET_KEY и YOOKASSA_RETURN_URL.
3. Скопируйте URL вебхука из админ-панели и укажите его в кабинете YooKassa.

Справочник

• YooKassa

FreeKassa

FreeKassa подключается как отдельный платежный метод. Входящие webhook-события обрабатываются через backend.

Настройка

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

Platega

Platega подключается как отдельный платежный провайдер. Внутри Minishop он может создавать несколько кнопок: основную legacy-кнопку, СБП/карту и crypto-кнопку.

Настройка

1. Включите PLATEGA_ENABLED.
2. Укажите PLATEGA_MERCHANT_ID и PLATEGA_SECRET.
3. Включите необходимые кнопки PLATEGA_SBP_ENABLED, PLATEGA_CRYPTO_ENABLED.
4. Скопируйте URL вебхука из админ-панели и укажите его в кабинете Platega.

Справочник

• Platega

SeverPay

SeverPay подключается как отдельный платежный метод с собственным MID, token и сроком жизни платежной ссылки.

Настройка

1. Включите SEVERPAY_ENABLED.
2. Укажите SEVERPAY_BASE_URL.
3. Заполните SEVERPAY_MID и SEVERPAY_TOKEN.
4. Скопируйте URL вебхука из админ-панели и укажите его в кабинете SeverPay.
5. При необходимости задайте SEVERPAY_LIFETIME_MINUTES.

Справочник

• SeverPay

Wata

Wata подключается как отдельный провайдер с bearer token, платежными ссылками и опциональной проверкой подписи webhook.

Настройка

1. Включите WATA_ENABLED.
2. Укажите WATA_BASE_URL и WATA_API_TOKEN.
3. Настройте WATA_LINK_TTL_MINUTES.
4. Скопируйте URL вебхука из админ-панели и укажите его в кабинете Wata.
5. При необходимости включите WATA_WEBHOOK_VERIFY_SIGNATURE.
6. Если используется проверка подписи, задайте WATA_PUBLIC_KEY.
7. Для IP-фильтрации заполните WATA_TRUSTED_IPS.

Ограничения

• WATA_LINK_TTL_MINUTES должен быть от 15 до 43200.

Справочник

• 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 вебхука из админ-панели и укажите его в CryptoPay.

Проверка

• Testnet-токен должен использоваться только с testnet.
• Mainnet-токен должен использоваться только с mainnet.
• Если сумма или asset выглядят неверно, проверьте сочетание CRYPTOPAY_CURRENCY_TYPE и CRYPTOPAY_ASSET.

Справочник

• CryptoPay

Heleket

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.
7. Скопируйте URL вебхука из админ-панели и укажите его в кабинете Heleket.
8. При необходимости включите HELEKET_VERIFY_WEBHOOK_SIGNATURE.
9. Для IP-фильтрации заполните HELEKET_TRUSTED_IPS.

Ограничения

• HELEKET_LIFETIME_SECONDS должен быть от 300 до 43200.

Справочник

• Heleket

PayKilla

PayKilla используется для крипто-инвойсов V2 через hosted checkout https://gopay.paykilla.com/{invoice_id}.

API-запросы подписываются HMAC-SHA256. Webhook проверяется по заголовку X-API-SIGN и raw body.

Особенности

• PayKilla строго валидирует текстовые поля invoice.
• В purpose и description Minishop отправляет простой английский текст <WEBAPP_TITLE> payment <id>.
• Локализованное описание платежа остается только внутри Minishop.
• ASCII-safe sanitizer допускает ASCII-буквы, цифры, пробелы, _, ., ,.

Валюта invoice

Minishop создает invoice в валюте, которую PayKilla принимает в поле currency.

Если валюта тарифа входит в PAYKILLA_INVOICE_CURRENCIES, сумма отправляется как есть.

Если валюта тарифа не входит в список, сумма конвертируется в PAYKILLA_CURRENCY. По умолчанию рублевые тарифы конвертируются в USD через ExchangeRate-API с кэшем PAYKILLA_EXCHANGE_RATE_CACHE_SECONDS.

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.
6. Сохраните secretKey в PAYKILLA_SECRET_KEY.

Webhook

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. Оставьте PAYKILLA_VERIFY_WEBHOOK_SIGNATURE=True.

Настройка

1. Включите PAYKILLA_ENABLED.
2. Укажите PAYKILLA_API_KEY и PAYKILLA_SECRET_KEY.
3. Оставьте PAYKILLA_CURRENCY=USD, если PayKilla не принимает валюту тарифов как invoice currency.
4. В PAYKILLA_INVOICE_CURRENCIES укажите валюты invoice, например USD,EUR.
5. В PAYKILLA_PAYMENT_CURRENCIES начните с USDTTRC.

Справочник

• PayKilla

Telegram Stars

Telegram Stars используются напрямую и поддерживаются в legacy-ценах и JSON-каталоге тарифов.

Где используются

• Цены period-подписок.
• Пакеты трафика.
• Premium-докупки.
• HWID-докупки, если они включены в каталоге тарифов.

Настройка

1. Включите STARS_ENABLED.
2. Проверьте Stars-цены в legacy-настройках или JSON-каталоге.
3. Убедитесь, что цена округляется до целого количества Stars.
4. Проверьте сценарии смены тарифа.

Ограничения

• Отдельный платежный webhook не нужен.
• Stars-события приходят через webhook Telegram-бота: WEBHOOK_BASE_URL + /tg/webhook.
• XTR/Stars-докупки не конвертируются без явно заданного курса.

Справочник

• Переменные платежей
• Тарифы