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