Приём платежей с помощью «ЮKassa»

Чтобы ваши абоненты могли оплачивать услуги в личном кабинете и в Telegram-боте с помощью ЮKassa, последовательно выполните шаги настройки.

Личный кабинет ЮKassa
Административный интерфейс LANBilling
Скрипт для callback-уведомлений
Скрипт для автоматических платежей
Конфигурационный файл

Личный кабинет ЮKassa

Зарегистрируйтесь в ЮKassa. После заключения договора в ЮKassa будет создан ваш магазин.
Для интеграции вам понадобятся два параметра. Найдите их в ЮKassa.
- shopID отображается напротив названия магазина в разделе «Операции».
- Секретный ключ API можно посмотреть в разделе «Интеграция» — «Ключи API».
Укажите в ЮKassa, где располагается скрипт callback-уведомлений kassa.py. Для этого перейдите в раздел «Интеграция» — «HTTP-уведомления» и в поле «URL для уведомлений» введите путь до файла на вашем веб-сервере.

Создать профиль менеджера для ВПС

Создайте профиль для платёжной системы в LANBilling.

Задать настройки ВПС

Перейдите в раздел «Настройки» — «Настройки ВПС».

Нажмите «Добавить».
Выберите профиль менеджера, созданный ранее. Также выберите оператора, для которого будет действовать ВПС.

Вы можете настроить несколько экземпляров одной платёжной системы. Для каждой из них пара менеджер/оператор должна быть уникальной.
В поле «ВПС» выберите «ЮКassa». Появятся расширенные настройки этой платёжной системы.

Некоторые поля заполнятся автоматически. Как правило, их не нужно редактировать — это настройки, которые меняются очень редко на стороне платёжной системы.
- URL проведения платежа — https://api.yookassa.ru/v3/payments
Введите комментарий. Это поле обязательно для заполнения. Если вы используете несколько экземпляров одной ВПС, комментарий позволит вам отличать их друг от друга.
Идентификатор магазина — можно посмотреть в личном кабинете ЮKassa.
Возможность подключать автоплатежи — позволяет вашим клиентам подключать автооплату в личном кабинете и Telegram-боте. По умолчанию возможность включена.

Подробнее о том, как устроены автоплатежи
Класс платежа — укажите идентификатор категории платежей. Он будет присваиваться платежам, совершённым вашими клиентами.
Код валюты (по ISO 4217) — по умолчанию используется валюта «рубли». Вы можете указать другую валюту. В договорах оператора, для которого вы настраиваете ВПС, должна быть указана соответствующая валюта.
Параметры покупателя для формирования чека — выберите, куда отправлять чек клиенту:
- Электронная почта
- Мобильный телефон
Описание платежа, отображаемое для пользователя — составьте шаблон описания, которое увидит ваш клиент, когда клиент будет пополнять баланс. В шаблоне можно использовать переменные:
- {amount} — сумма платежа
- {agrmid} — идентификатор договора
- {agrmnum} — номер договора
- {email} — email клиента
- {mobile} — мобильный телефон клиента
- {agrnums} — номера договоров (если оплата по нескольким договорам)
- {currency} — валюта (берется из параметра currency)
Пример.

В настройках задан шаблон описания: Оплата {amount} {currency} по договору {agrnum}

При оплате пользователь увидит свои данные: Оплата 2 500 руб. по договору Contract_1
Минимальный размер платежа — позволяет задать минимальную сумму, на которую ваши абоненты могут пополнить баланс в личном кабинете или Telegram-боте. Если не хотите использовать это ограничение, укажите значение 0.
Минимальный размер рекуррентного платежа — если вы работаете с автоплатежами, можно задать минимальную сумму автооплаты.
Признак способа расчета — выберите признак, который будет присваиваться платежам:
- Полный расчет
- Полная предоплата
- Частичная предоплата
- Аванс
Признак предмета расчета — выберите предмет расчёта, который будет присваиваться платежам:
- Платёж
- Товар
- Услуга
- Другое
Название товара — введите наименование, которое будет подставляться в чек.
Описание автоплатежа, отображаемое для пользователя — текст, который будет отображаться для автоплатежей.
URL, на который вернётся пользователь после подтверждения или отмены платежа — адрес страницы, на которую попадёт клиент после завершения оплаты.
Секретный ключ — ключ, который используется для идентификации сервиса в ЮKassa. Инструкция по генерации ключа.
Система налогообложения — выберите СНО организации, для которой настраиваете платёжную систему:
- Общая
- Упрощенная (доходы)
- Упрощенная (доходы минус расходы)
Использовать обычную оплату — возможность использовать обычную оплату картой (не СБП). По умолчанию флаг установлен. Если хотите использовать только способ оплаты «СБП», снимите флаг.
Использовать оплату по СБП — по умолчанию флаг установлен. Если хотите использовать только обычный способ оплаты картой, снимите флаг.
Сохраните настройки ВПС.

Скрипт для callback-уведомлений kassa.py

Скрипт нужен, чтобы фиксировать в LANBilling результаты оплат. Он обрабатывает запросы от платёжной системы — в них содержится информация об операциях. На основании этих данных скрипт создаёт платежи в биллинге.

Настройка различается для разных ОС.

Скопируйте файл kassa.py в директорию исполняемых скриптов вашего веб-сервера:
```
cp /usr/local/billing/payments/yandex/kassa.py /var/www/cgi-bin/
```
``
Укажите в файле настройки доступа. Пример:
```
# Настройки логирования
YANDEX_LOG = '/var/log/billing/weblogs/yandex.kassa.log'
# Параметры подключения к LBcore
HOST = '127.0.0.1'
PORT = 34012
MANAGER = 'super_pay'
PASSWORD = '12345'
OPER_ID = 1
```
``
- YANDEX_LOG — путь к файлу с логами.
- HOST и PORT — IP-адрес и порт для подключения к LBcore.
- MANAGER и PASSWORD — логин и пароль от профиля платёжной системы в LANBilling. Укажите реквизиты того же профиля, которые задали при настройке в административном интерфейсе.
- OPER_ID — ID оператора в биллинге. Укажите идентификатор того же оператора, который задали при настройке в административном интерфейсе.
Сделайте скрипт исполняемым:
```
chmod +x /var/www/cgi-bin/kassa.py
```
``

Скопируйте файл kassa.py в директорию исполняемых скриптов вашего веб-сервера:
```
cp /usr/local/billing/payments/yandex/kassa.py /usr/lib/cgi-bin/
```
``
Укажите в файле настройки доступа. Пример:
```
# Настройки логирования
YANDEX_LOG = '/var/log/billing/weblogs/yandex.kassa.log'
# Параметры подключения к LBcore
HOST = '127.0.0.1'
PORT = 34012
MANAGER = 'super_pay'
PASSWORD = '12345'
OPER_ID = 1
```
``
- YANDEX_LOG — путь к файлу с логами.
- HOST и PORT — IP-адрес и порт для подключения к LBcore.
- MANAGER и PASSWORD — логин и пароль от профиля платёжной системы в LANBilling. Укажите реквизиты того же профиля, которые задали при настройке в административном интерфейсе.
- OPER_ID — ID оператора в биллинге. Укажите идентификатор того же оператора, который задали при настройке в административном интерфейсе.
Сделайте скрипт исполняемым:
```
chmod +x /usr/lib/cgi-bin/kassa.py
```
``

Скопируйте файл kassa.py в директорию исполняемых скриптов вашего веб-сервера:
```
cp /usr/local/billing/payments/yandex/kassa.py /usr/local/www/apache24/cgi-bin/
```
``
Укажите в файле настройки доступа. Пример:
```
# Настройки логирования
YANDEX_LOG = '/var/log/billing/weblogs/yandex.kassa.log'
# Параметры подключения к LBcore
HOST = '127.0.0.1'
PORT = 34012
MANAGER = 'super_pay'
PASSWORD = '12345'
OPER_ID = 1
```
``
- YANDEX_LOG — путь к файлу с логами.
- HOST и PORT — IP-адрес и порт для подключения к LBcore.
- MANAGER и PASSWORD — логин и пароль от профиля платёжной системы в LANBilling. Укажите реквизиты того же профиля, которые задали при настройке в административном интерфейсе.
- OPER_ID — ID оператора в биллинге. Укажите идентификатор того же оператора, который задали при настройке в административном интерфейсе.
Сделайте скрипт исполняемым:
```
chmod +x /usr/local/www/apache24/cgi-bin/kassa.py
```
``

Скрипт для автоматических платежей kassa_recurrent_payment.py

Выполните эти шаги, если вы работаете с автоплатежами.

Убедитесь, что установлен Python 3, а также дополнительные пакеты. Список различается в зависимости от ОС.

CentOS, RHEL, РЕД ОС Debian, Astra Linux FreeBSD

Необходимый пакет: python3-requests.

Необходимый пакет: python3-requests.

Необходимый пакет: py39-requests.
Скопируйте скрипт kassa_recurrent_payment.py в директорию /usr/local/billing/pymodules/:
```
cp /usr/local/billing/payments/yandex/kassa_recurrent_payment.py /usr/local/billing/pymodules/
```
``
Укажите в файле настройки доступа. Пример:
```
MANAGER = 'super_pay'
PASSWORD = '12345'
OPER_ID = 1
```
``
- MANAGER и PASSWORD — логин и пароль от профиля платёжной системы в LANBilling. Укажите реквизиты того же профиля, которые задали при настройке в административном интерфейсе.
- OPER_ID — ID оператора в биллинге. Укажите идентификатор того же оператора, который задали при настройке в административном интерфейсе. Автоплатежи будут выполняться только по договорам этого оператора.
Перезапустите модуль LBcore. Команды различаются в разных ОС.

Debian, CentOS, RHEL, РЕД ОС, Astra Linux FreeBSD
```
systemctl restart lbcore
```
```
service lbcore restart
```

Конфигурационный файл yooKassa.ini

Действия различаются для разных ОС.

Откройте файл конфигурации yooKassa.ini:
```
nano /etc/lanbilling/phpclient/client/yooKassa.ini
```
``

Включите платёжную систему, чтобы абоненты смогли вносить через неё оплаты в личном кабинете и Telegram-боте:
```
[yooKassa]
enabled = true
```
``

Убедитесь, что настройки совпадают с теми, которые вы задали для ВПС в административном интерфейсе.

Пример файла:
```
; Настройка ЮKassa
[yooKassa]
enabled = true
; Идентификатор менеджера, работающего с данной ВПС
epsManagerId = '1'
; Возможность подключать автоплатежи
allowAutoPayments = true
; Идентификатор магазина. Указан в личном кабинете кассы.
shopId = 000
; Секретный ключ - это уникальная последовательность символов, которая используется для идентификации сервиса в ЮKassa
apiKey = '1111111111'
; Код системы налогообложения
tax = 1
; Код валюты в формате ISO-4217(https://www.iso.org/iso-4217-currency-codes.html)
currency = 'RUB'
; Описание транзакции, которое вы увидите в личном кабинете ЮKassa, а пользователь — при оплате.
description = 'Оплата {amount} {currency} по договору {agrnum}'
; Параметры телефон или эл. почта покупателя для формирования чека.
customerContact = 'email'
;Признак предмета расчета - категория этого товара для налоговой.
paymentSubject = 'payment'
; Признак способа расчета  - категория способа оплаты для налоговой.
paymentMode = 'full_payment'
; Сумма минимального платежа
minPaymentAmount = 10
; Возможность использовать обычную оплату
useCardPayment = true
; Возможность использовать СБП оплату
useSbpPayment = true
```
``
- epsManagerId — идентификатор профиля платёжной системы в LANBilling. Укажите идентификатор того же профиля, который создали для этой ВПС в административном интерфейсе.
- allowAutoPayments — возможность подключать автоплатежи.
  - true — клиенты смогут подключать автооплату в личном кабинете.
  - false — клиенты несмогут подключать автооплату в личном кабинете.
- shopId — идентификатор магазина. Его можно посмотреть в личном кабинете ЮKassa.
- apiKey — секретный ключ, который используется для идентификации сервиса в ЮKassa.
- tax — система налогообложения. Укажите СНО оператора:
  - 1 — общая система налогообложения
  - 2 — упрощенная (УСН, доходы)
  - 3 — упрощенная (УСН, доходы минус расходы)
- currency — код валюты в формате ISO-4217.
- description — описание платежа, отображаемое для пользователя.
- customerContact — параметры покупателя для формирования чека. Укажите, куда отправлять чек клиенту:
  - email — электронная почта
  - phone — мобильный телефон
- paymentSubject — признак предмета расчета, категория товара для налоговой.
  - payment — платёж
  - commodity — товар
  - service — услуга
  - another — другое
- paymentMode — признак способа расчета, категория способа оплаты для налоговой.
  - full_payment — полный расчёт
  - full_prepayment — полная предоплата
  - partial_prepayment — частичная предоплата
  - advance — аванс
- minPaymentAmount — позволяет задать минимальную сумму, на которую ваши абоненты могут пополнить баланс. Если не хотите использовать это ограничение, укажите значение 0.
- useCardPayment — включает возможность обычной оплаты картой (не СБП) в личном кабинете и Telegram-боте.
  - true — клиенты смогут использовать обычную оплату картой.
  - false — клиенты не смогут использовать обычную оплату картой.
- useSbpPayment — включает возможность оплаты по СБП в личном кабинете и Telegram-боте.
  - true — клиенты смогут оплачивать услуги по СБП.
  - false — клиенты не смогут оплачивать услуги по СБП.

Сохраните конфигурационный файл. Сериализуйте изменения:
```
/usr/local/sbin/lbwebcfg -y client /etc/lanbilling/phpclient/client/
```
``

Откройте файл конфигурации yooKassa.ini:
```
nano /usr/local/etc/lanbilling/phpclient/client/yooKassa.ini
```
``

Включите платёжную систему, чтобы абоненты смогли вносить через неё оплаты в личном кабинете и Telegram-боте:
```
[yooKassa]
enabled = true
```
``

Убедитесь, что настройки совпадают с теми, которые вы задали для ВПС в административном интерфейсе.

Пример файла:
```
; Настройка ЮKassa
[yooKassa]
enabled = true
; Идентификатор менеджера, работающего с данной ВПС
epsManagerId = '1'
; Возможность подключать автоплатежи
allowAutoPayments = true
; Идентификатор магазина. Указан в личном кабинете кассы.
shopId = 000
; Секретный ключ - это уникальная последовательность символов, которая используется для идентификации сервиса в ЮKassa
apiKey = '1111111111'
; Код системы налогообложения
tax = 1
; Код валюты в формате ISO-4217(https://www.iso.org/iso-4217-currency-codes.html)
currency = 'RUB'
; Описание транзакции, которое вы увидите в личном кабинете ЮKassa, а пользователь — при оплате.
description = 'Оплата {amount} {currency} по договору {agrnum}'
; Параметры телефон или эл. почта покупателя для формирования чека.
customerContact = 'email'
;Признак предмета расчета - категория этого товара для налоговой.
paymentSubject = 'payment'
; Признак способа расчета  - категория способа оплаты для налоговой.
paymentMode = 'full_payment'
; Сумма минимального платежа
minPaymentAmount = 10
; Возможность использовать обычную оплату
useCardPayment = true
; Возможность использовать СБП оплату
useSbpPayment = true
```
``
- epsManagerId — идентификатор профиля платёжной системы в LANBilling. Укажите идентификатор того же профиля, который создали для этой ВПС в административном интерфейсе.
- allowAutoPayments — возможность подключать автоплатежи.
  - true — клиенты смогут подключать автооплату в личном кабинете.
  - false — клиенты несмогут подключать автооплату в личном кабинете.
- shopId — идентификатор магазина. Его можно посмотреть в личном кабинете ЮKassa.
- apiKey — секретный ключ, который используется для идентификации сервиса в ЮKassa.
- tax — система налогообложения. Укажите СНО оператора:
  - 1 — общая система налогообложения
  - 2 — упрощенная (УСН, доходы)
  - 3 — упрощенная (УСН, доходы минус расходы)
- currency — код валюты в формате ISO-4217.
- description — описание платежа, отображаемое для пользователя.
- customerContact — параметры покупателя для формирования чека. Укажите, куда отправлять чек клиенту:
  - email — электронная почта
  - phone — мобильный телефон
- paymentSubject — признак предмета расчета, категория товара для налоговой.
  - payment — платёж
  - commodity — товар
  - service — услуга
  - another — другое
- paymentMode — признак способа расчета, категория способа оплаты для налоговой.
  - full_payment — полный расчёт
  - full_prepayment — полная предоплата
  - partial_prepayment — частичная предоплата
  - advance — аванс
- minPaymentAmount — позволяет задать минимальную сумму, на которую ваши абоненты могут пополнить баланс. Если не хотите использовать это ограничение, укажите значение 0.
- useCardPayment — включает возможность обычной оплаты картой (не СБП) в личном кабинете и Telegram-боте.
  - true — клиенты смогут использовать обычную оплату картой.
  - false — клиенты не смогут использовать обычную оплату картой.
- useSbpPayment — включает возможность оплаты по СБП в личном кабинете и Telegram-боте.
  - true — клиенты смогут оплачивать услуги по СБП.
  - false — клиенты не смогут оплачивать услуги по СБП.

Сохраните конфигурационный файл. Сериализуйте изменения:
```
/usr/local/sbin/lbwebcfg -y client /usr/local/etc/lanbilling/phpclient/client/
```
``

Настройка завершена. Теперь абоненты могут пополнять баланс в личном кабинете и в Telegram-боте с помощью этой платёжной системы.

Проверка взаимодействия

Вы можете протестировать возможности оплаты. Подробнее об этом читайте на сайте ЮKassa.

Как устроена работа с НДС

Система берёт значение ставки НДС из карточки оператора. Если в карточке оператора не задана ставка НДС или значение не удаётся распознать — применяется значение «Без НДС».

При пополнении сразу нескольких договоров для каждого из них создаётся отдельная позиция в чеке с соответствующей ставкой НДС. Это связано с тем, что в разных договорах могут быть указаны разные операторы, и у каждого из них может быть своя ставка НДС.

Есть вопросы по документации? Пожалуйста, напишите их на itdep@lanbilling.ru.