Платёжные системы

Настройка приёма онлайн-платежей: через что клиент платит из личного кабинета и мобильного приложения, какая берётся комиссия и с каких адресов принимается webhook.

Обучающее видео 3:03

Как настроить приём онлайн-оплат: общие настройки и кассы организаций, активная система и комиссия, секретные ключи, проверка подключения, безопасность вебхука и работа с телефона.

1920×1080 с озвучкой Скачать

Наборы настроек: общие и кассы организаций

Страница правит два разных набора, между ними переключает полоса в шапке:

Общие настройки — глобальные ключи. По ним платят клиенты организации по умолчанию и все, у кого организация не проставлена.
Касса организации — собственные реквизиты приёма оплат конкретного юрлица (OrgPaymentSettings). При создании платежа биллинг сначала берёт кассу организации клиента и только при её отсутствии откатывается на общие ключи.

Если хотя бы у одной организации настроена своя касса, в общем режиме показывается предупреждение со ссылками на эти кассы: правки в общих настройках на их клиентов не влияют. Тумблер «Использовать свою кассу» выключает переопределение — клиенты организации возвращаются на общие ключи.

Что остаётся общим для всех организаций

Активная платёжная система, комиссия, валюта W1, секрет подписи Generic/UCS и белый список IP. На уровне организации переопределяются только реквизиты кассы, адреса возврата клиента и расчётный счёт приёма оплат.

Секретные ключи

Секреты в браузер не отдаются: в поле показывается только маска с опознавательным хвостом (••••••••2bc9). Пустое поле при сохранении означает «не менять» — чтобы заменить ключ, введите новый.

Проверка подключения

Кнопка «Проверить подключение» различает три исхода, а не два:

Статус	Что значит
✓ зелёный	Ключ подтверждён сервером платёжной системы (ЮKassa REST API v3, запрос `/v3/me`).
⚠ жёлтый	Конфигурация заполнена, но протокол не позволяет проверить ключ запросом — старый HTTP-протокол ЮKassa и Wallet One. Работоспособность подтверждается только тестовым платежом.
✕ красный	Отказ: неверные учётные данные, недоступен узел, не заполнены обязательные поля.

Проверку можно выполнить для любой системы, в том числе неактивной — переключать боевой приём платежей для этого не нужно. Неактивная система помечается пунктирной рамкой и бейджем «не активна», её поля остаются читаемыми и доступными для правки.

Провайдеры

ЮKassa (REST API v3) — современный API, рекомендован. Параметры: shopId, secret key (формат live_XXX или test_XXX), webhook URL (привязывается в личном кабинете ЮKassa).
ЮKassa HTTP — старый протокол на форме POST. Параметры: shopId, scid, shopPassword. Используется только для legacy-договоров.
Wallet One (W1) — альтернативный провайдер. Параметры: merchant ID, secret key, валюта (643 = RUB), URL успеха и ошибки.
Универсальный webhook — единый endpoint /lk/payments/webhook/, который принимает все форматы (W1, ЮKassa HTTP, ЮKassa REST v3, Generic) и зачисляет на счёт.

Комиссия

Задаётся в процентах (например, 4,5), максимум 20 %; значение проверяется на сервере. Комиссия добавляется клиенту сверху: при пополнении на 500 ₽ и ставке 4,5 % платёжная система спишет 522,50 ₽, а на счёт зачислится ровно 500 ₽. Карточка справа пересчитывает пример при вводе.

Безопасность webhook

Белый список IP (CIDR через запятую) — запросы с других адресов получают 403. Пустой список означает набор по умолчанию: ЮKassa, W1 и localhost. Кнопки-пресеты добавляют адреса без дублей, «Очистить» запрашивает подтверждение.
Секрет подписи Generic/UCS — обязателен для приёма через «Единую кассу». Пока он не задан, канал помечается бейджем «не задан — канал отключён», а webhook отвечает 403. Кнопка «Генерировать» создаёт секрет криптостойким генератором браузера.

Аудит и сохранение

Каждое изменение пишется в журнал аудита (PAYMENT_SETTINGS) с автором и перечнем изменённых параметров: для обычных полей — старое и новое значение, для секретов — только факт замены. Кнопка «Сохранить настройки» закреплена внизу формы, не исчезает после сохранения и снова гаснет, когда изменений нет. Перезапуск сервера вынесен отдельной кнопкой и требует подтверждения.

Подробное описание API — на отдельной странице

Endpoints, схемы платежей, REST API v3 / HTTP, Wallet One, Mobile API — в разделе API, секция Платёжные API.

Маппа платёжных систем → FinTypes

При успешном платеже webhook (lk/services/payment.py::_credit_abonent) создаёт FinanceOperations с типом операции, выбираемым по pay_system. Маппа настраивается через /admin/dictionary/FinTypes/ + ключи SystemSettings:

pay_system	SystemSettings ключ	FinTypes по умолчанию
`YooKassa`	`LK_PAYMENT_OPTYPE_YOOKASSA`	«ЮKassa» (приход +1)
`W1`	`LK_PAYMENT_OPTYPE_W1`	«Wallet One (W1)» (приход +1)
`card`	`LK_PAYMENT_OPTYPE_CARD`	type_id=40 «Платёж с карты»
`generic` / fallback	`LK_PAYMENT_OPTYPE_GENERIC`	type_id=23 «Оплата через платежные системы»

Зачем это нужно: у каждой платёжной системы свой FinTypes, и бухгалтерия разделяет источники — отчёты «итого через ЮKassa за месяц» работают через простой фильтр по op_type_id без парсинга поля descr.

Как изменить:

Создать новый тип в Справочники → Типы фин. операций (например, «СБП» или «T-Bank»).
Установить SystemSettings.value для соответствующего ключа = type_id нового типа. Через /admin/settings/system/ или management-команду set_system_setting LK_PAYMENT_OPTYPE_YOOKASSA 51.
Webhook автоматически подхватит новое значение при следующем платеже (без рестарта).

Старые операции (под type_id=23) не переразмечаются — они остаются в истории под прежним типом. Только платежи, начисленные после миграции 0115, получают новые типы. Это безопасно: отчёты с интервалом «после 2026-05-08» получат правильную разбивку, ранние периоды останутся как есть.