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.
2026-06-10 23:32:39 +03:00
parent 2074e934ce
commit dc4da78fc4
5 changed files with 51 additions and 3 deletions
@@ -16,7 +16,7 @@ Remnawave Minishop - Telegram-бот и Web App (Mini App) для продажи
 - Web App / Mini App с входом через Telegram или email;
 - встроенные инструкции установки в Mini App: личный экран `/install` и публичная ссылка `/s/<token>` для передачи инструкции;
 - пробный период, промокоды и реферальная программа;
- оплата через 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`.

@@ -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`.
@@ -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` или коде.
@@ -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-каталоге тарифов.
@@ -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 список валют нужно держать в соответствии с условиями вашего мерчанта.