From dc4da78fc49894203f31e04bdb4c640276ce2ded Mon Sep 17 00:00:00 2001 From: 3252a8 <3252a8@proton.me> Date: Wed, 10 Jun 2026 23:32:39 +0300 Subject: [PATCH] docs: document LAVA provider setup Describe LAVA Business configuration: env keys, webhook URL and signature scheme, RUB-only invoices, and the include-services filter. Mention LAVA in the provider lists of the README, admin panel page, and tariff currency matrix. --- README.md | 2 +- docs/configuration/env-vars.md | 23 ++++++++++++++++++++++- docs/features/admin-panel.md | 2 +- docs/features/payments.md | 26 ++++++++++++++++++++++++++ docs/features/tariffs.md | 1 + 5 files changed, 51 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 3009c09..7ca5fc4 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ Remnawave Minishop - Telegram-бот и Web App (Mini App) для продажи - Web App / Mini App с входом через Telegram или email; - встроенные инструкции установки в Mini App: личный экран `/install` и публичная ссылка `/s/` для передачи инструкции; - пробный период, промокоды и реферальная программа; -- оплата через YooKassa, FreeKassa, Platega, SeverPay, Wata, CryptoPay, Heleket, PayKilla и Telegram Stars; +- оплата через YooKassa, FreeKassa, Platega, SeverPay, Wata, CryptoPay, Heleket, PayKilla, LAVA и Telegram Stars; - тикеты поддержки в Web App и внешняя ссылка на поддержку; - раздел "Мои устройства" при включенном `MY_DEVICES_SECTION_ENABLED`. diff --git a/docs/configuration/env-vars.md b/docs/configuration/env-vars.md index 61b9b32..2f5c46b 100644 --- a/docs/configuration/env-vars.md +++ b/docs/configuration/env-vars.md @@ -219,7 +219,7 @@ proxy/Docker gateway и может отклонить валидный webhook. | Переменная | Назначение | | --- | --- | -| `PAYMENT_METHODS_ORDER` | Порядок кнопок оплаты: `severpay,wata,freekassa,platega,yookassa,stars,cryptopay,heleket,paykilla`. | +| `PAYMENT_METHODS_ORDER` | Порядок кнопок оплаты: `severpay,wata,freekassa,platega,yookassa,stars,cryptopay,heleket,paykilla,lava`. | | `SUBSCRIPTION_PURCHASE_DESCRIPTION_ENABLED` | Показывать описание подписки перед выбором срока. | | `SUBSCRIPTION_PURCHASE_DESCRIPTION_RU` / `SUBSCRIPTION_PURCHASE_DESCRIPTION_EN` | Локализованное описание подписки. | | `PAYMENT_REQUEST_TIMEOUT_SECONDS` | Общий таймаут одного API-запроса к платёжному провайдеру, в секундах. По умолчанию `20`. | @@ -237,6 +237,7 @@ proxy/Docker gateway и может отклонить валидный webhook. | `CRYPTOPAY_ENABLED` | Включает CryptoPay. | | `HELEKET_ENABLED` | Включает Heleket. | | `PAYKILLA_ENABLED` | Включает PayKilla. | +| `LAVA_ENABLED` | Включает LAVA. | Конкретные ключи отображения: @@ -301,6 +302,12 @@ PAYMENT_PAYKILLA_WEBAPP_ICON PAYMENT_PAYKILLA_TELEGRAM_LABEL_RU PAYMENT_PAYKILLA_TELEGRAM_LABEL_EN PAYMENT_PAYKILLA_TELEGRAM_EMOJI +PAYMENT_LAVA_WEBAPP_LABEL_RU +PAYMENT_LAVA_WEBAPP_LABEL_EN +PAYMENT_LAVA_WEBAPP_ICON +PAYMENT_LAVA_TELEGRAM_LABEL_RU +PAYMENT_LAVA_TELEGRAM_LABEL_EN +PAYMENT_LAVA_TELEGRAM_EMOJI ``` ### YooKassa @@ -416,6 +423,20 @@ Webhook настраивается в PayKilla Dashboard: **Settings -> Webhooks | `PAYKILLA_WEBHOOK_URL` | Точный публичный webhook URL для проверки подписи, если он отличается от `WEBHOOK_BASE_URL` + `/webhook/paykilla`. | | `PAYKILLA_TRUSTED_IPS` | Необязательный список доверенных IP webhook-источников. | +### LAVA + +Счета LAVA Business выставляются только в рублях. Исходящие запросы подписываются HMAC-SHA256 от raw body (заголовок `Signature`), webhook проверяется по заголовку `Authorization`. + +| Переменная | Назначение | +| --- | --- | +| `LAVA_BASE_URL` | Базовый URL API, по умолчанию `https://api.lava.ru`. | +| `LAVA_SHOP_ID` | ID магазина в LAVA Business. | +| `LAVA_SECRET_KEY` | Секретный ключ магазина для подписи исходящих API-запросов. | +| `LAVA_WEBHOOK_SECRET` | Дополнительный ключ магазина для проверки подписи webhook; если пусто, используется `LAVA_SECRET_KEY`. | +| `LAVA_RETURN_URL` | URL возврата после оплаты (`successUrl`/`failUrl`). | +| `LAVA_LIFETIME_MINUTES` | Время жизни счета в минутах: 1..7200. | +| `LAVA_INCLUDE_SERVICES` | Способы оплаты на странице счета через запятую, например `card,sbp`. | + ## Тарифы и legacy-цены Рекомендуемый способ настройки тарифов - раздел **Система -> Тарифы** в админке. Он сохраняет JSON в `TARIFFS_CONFIG_PATH`. diff --git a/docs/features/admin-panel.md b/docs/features/admin-panel.md index 8ceb670..4ac108f 100644 --- a/docs/features/admin-panel.md +++ b/docs/features/admin-panel.md @@ -52,7 +52,7 @@ - внешний вид и доступность Web App: название, цвет, логотип и `WEBAPP_ENABLED`; - инструкции подключения: `SUBSCRIPTION_GUIDES_ENABLED`, `SUBSCRIPTION_GUIDES_BOT_MENU_ENABLED`, чтение конфига из Remnawave Panel, JSON-переопределение и резервный путь к файлу; - legacy-тарифы без JSON-каталога: периоды подписки, RUB/Stars цены, реферальные бонусы и пакеты трафика; -- платежные провайдеры: включение методов, порядок кнопок, публичные параметры и секреты YooKassa, FreeKassa, Platega, SeverPay, Wata, CryptoPay, Heleket и Stars, а также текст и иконки кнопок оплаты; +- платежные провайдеры: включение методов, порядок кнопок, публичные параметры и секреты YooKassa, FreeKassa, Platega, SeverPay, Wata, CryptoPay, Heleket, LAVA и Stars, а также текст и иконки кнопок оплаты; - пробный период, приветственный реферальный бонус, уведомления, логирование, Telegram антифлуд, поддержка, раздел устройств, лимит устройств и legacy-лимиты трафика. Секретные поля помечены как secret и не должны использоваться для произвольного просмотра старых значений. Настройки, которых нет в manifest, остаются только в `.env` или коде. diff --git a/docs/features/payments.md b/docs/features/payments.md index 3a5d7fc..bab4d76 100644 --- a/docs/features/payments.md +++ b/docs/features/payments.md @@ -44,6 +44,7 @@ reverse proxy должен прокидывать `X-Forwarded-For`, а его I | 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; включите события оплаты инвойсов. | +| LAVA | `WEBHOOK_BASE_URL` + `/webhook/lava` | Передается автоматически как `hookUrl` при создании счета; можно также указать в кабинете LAVA Business. | | Telegram Stars | Отдельный платежный webhook не нужен | Stars-события приходят через webhook Telegram-бота: `WEBHOOK_BASE_URL` + `/tg/webhook`. | После настройки сделайте тестовый платеж и проверьте, что в логах `backend` видно входящий `POST` на нужный путь. Если провайдер сообщает, что адрес недоступен, сначала проверьте DNS/HTTPS и reverse proxy для `WEBHOOK_BASE_URL`, затем убедитесь, что путь начинается ровно с `/webhook/...` без `/api`, `/auth` и frontend-домена. @@ -243,6 +244,31 @@ Redirect URLs в PayKilla не отправляются. Завершение п - [PayKilla](../configuration/env-vars.md#paykilla) +## LAVA + +LAVA Business используется для рублевых оплат картами и СБП через счета `https://api.lava.ru`. + +Исходящие API-запросы подписываются HMAC-SHA256 от raw body, подпись передается в заголовке `Signature`. Webhook проверяется по заголовку `Authorization`: принимается подпись raw body или sorted-keys JSON (legacy PHP SDK). + +### Особенности + +- Счета выставляются только в рублях (`RUB`). +- `hookUrl` передается автоматически при создании счета, если задан `WEBHOOK_BASE_URL`. +- `LAVA_INCLUDE_SERVICES` ограничивает способы оплаты на странице счета, например `card,sbp`. +- При успешной оплате сумма из webhook сверяется с суммой платежа; расхождение отклоняется. + +### Настройка + +1. Включите `LAVA_ENABLED`. +2. Укажите `LAVA_SHOP_ID` и `LAVA_SECRET_KEY` из кабинета LAVA Business. +3. Если магазин использует отдельный дополнительный ключ для вебхуков, задайте `LAVA_WEBHOOK_SECRET`; пустое значение означает использование `LAVA_SECRET_KEY`. +4. При необходимости задайте `LAVA_LIFETIME_MINUTES` (1..7200) и `LAVA_RETURN_URL`. +5. Скопируйте URL вебхука из админ-панели и при необходимости укажите его в кабинете LAVA. + +### Справочник + +- [LAVA](../configuration/env-vars.md#lava) + ## Telegram Stars Telegram Stars используются напрямую и поддерживаются в legacy-ценах и JSON-каталоге тарифов. diff --git a/docs/features/tariffs.md b/docs/features/tariffs.md index 4ed0aee..3e0b1ff 100644 --- a/docs/features/tariffs.md +++ b/docs/features/tariffs.md @@ -69,6 +69,7 @@ Legacy-поля остаются алиасами: `prices_rub`, `conversion_rat | Heleket | настраиваемый список `HELEKET_SUPPORTED_CURRENCIES` | | Platega | настраиваемый список `PLATEGA_SUPPORTED_CURRENCIES` | | SeverPay | настраиваемый список `SEVERPAY_SUPPORTED_CURRENCIES` | +| LAVA | `RUB` | | Telegram Stars | `XTR`, отдельные Stars-цены | В админке раздел **Система → Тарифы** показывает текущую платежную валюту и матрицу провайдеров: включен ли метод, настроен ли сервис и будет ли он доступен при выбранной валюте. Для Platega, SeverPay и Heleket список валют нужно держать в соответствии с условиями вашего мерчанта.