Lava
Lava Business (lava.ru) — приём оплаты картой и СБП. Бот создаёт счёт через POST /business/invoice/create на api.lava.ru, юзер оплачивает на hosted-странице Lava и возвращается по successUrl. Валюта шлюза — RUB.
Каждый запрос к API бот подписывает HMAC-SHA256 от сырого тела запроса ключом secret_key (заголовок Signature). В счёт кладётся свой payment_id (orderId) — по нему вебхук привязывается к платежу; дополнительно сохраняется invoice_id от Lava.
Что понадобится
Магазин в кабинете Lava Business. Оттуда нужны три вещи: shopId магазина, секретный ключ API (им подписываются исходящие запросы) и секрет вебхуков (им Lava подписывает уведомления). Это два разных ключа — не путайте.
Настройка в кабинете
| Поле | Что это | Обязательное |
|---|---|---|
shop_id | shopId магазина из кабинета Lava | да |
secret_key | секретный ключ API — подпись исходящих запросов (заголовок Signature) | да |
webhook_secret | секрет вебхуков — проверка подписи входящих уведомлений | да |
Все ключи хранятся в БД в зашифрованном виде. Включите тумблер активности провайдера. Кнопка Тест у этого шлюза проверочного запроса к API не делает — правильность ключей подтвердит первый платёж. Дополнительно настраиваются отображаемое имя, комиссия для статистики и формы оплаты, которые видит юзер (карта / СБП).
Вебхук
https://ваш-домен/api/v1/payments/lavaУкажите этот URL как адрес уведомлений в кабинете Lava. Подпись приходит в заголовке Authorization (бот принимает её и из Signature) — это HMAC-SHA256 hex по сырому телу запроса с ключом webhook_secret. Для магазинов на старом PHP SDK Lava считает подпись иначе — по пересобранному JSON с сортировкой ключей; бот принимает оба варианта. Битая или отсутствующая подпись → HTTP 403.
Маппинг статуса из поля status:
| Статус Lava | Что делает бот |
|---|---|
success, paid | зачисляет платёж |
cancel, cancelled, canceled, expired, error, failed | закрывает платёж как отменённый |
| остальные | оставляет в ожидании |
Особенности
- Возвраты по API, рекурренты и сохранённые карты не поддерживаются — возврат делаете в кабинете Lava, в боте фиксируете результат: /payments/refunds.
- Опроса статуса у этого шлюза нет — зачисление зависит только от вебхука.
- Сумма из вебхука сверяется со счётом: если пришло меньше 90% ожидаемого, платёж бракуется как недоплата и не зачисляется.
- Комментарий к счёту обрезается до 255 символов,
successUrl— до 500; по умолчанию возврат ведёт в Telegram.
Платёж прошёл, а подписки нет?
У Lava нет API опроса статуса, поэтому реконсилятор этот шлюз не добьёт — единственный канал зачисления здесь вебхук. Если платежи виснут, первым делом проверьте URL уведомлений и webhook_secret. Как устроен пайплайн вебхуков — /payments/webhooks.