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

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

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

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

  1. Зарегистрируйтесь в ЮKassa. После заключения договора в ЮKassa будет создан ваш магазин.

  2. Для интеграции вам понадобятся два параметра. Найдите их в ЮKassa.

    • shopID отображается напротив названия магазина в разделе «Операции».
    • Секретный ключ API можно посмотреть в разделе «Интеграция» — «Ключи API».
    image

  3. Укажите в ЮKassa, где располагается скрипт callback-уведомлений kassa.py. Для этого перейдите в раздел «Интеграция» — «HTTP-уведомления» и в поле «URL для уведомлений» введите путь до файла на вашем веб-сервере.

    image

Административный интерфейс LANBilling

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

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

image

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

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

    image

  1. Нажмите «Добавить».

    image

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

    Вы можете настроить несколько экземпляров одной платёжной системы. Для каждой из них пара менеджер/оператор должна быть уникальной.

  3. В поле «ВПС» выберите «ЮКassa». Появятся расширенные настройки этой платёжной системы.

    image

    Некоторые поля заполнятся автоматически. Как правило, их не нужно редактировать — это настройки, которые меняются очень редко на стороне платёжной системы.

    • URL проведения платежа — https://api.yookassa.ru/v3/payments

  4. Введите комментарий. Это поле обязательно для заполнения. Если вы используете несколько экземпляров одной ВПС, комментарий позволит вам отличать их друг от друга.

    image

  5. Идентификатор магазина — можно посмотреть в личном кабинете ЮKassa.

    image

  6. Возможность подключать автоплатежи — позволяет вашим клиентам подключать автооплату в личном кабинете. По умолчанию возможность включена.

    Подробнее о том, как устроены автоплатежи

    image

  7. Класс платежа — укажите идентификатор категории платежей. Он будет присваиваться платежам, совершённым вашими клиентами в личном кабинете.

  8. Код валюты (по ISO 4217) — по умолчанию используется валюта «рубли». Вы можете указать другую валюту. В договорах оператора, для которого вы настраиваете ВПС, должна быть указана соответствующая валюта.

    image

  9. Параметры покупателя для формирования чека — выберите, куда отправлять чек клиенту:

    • Электронная почта
    • Мобильный телефон
    image

  10. Описание платежа, отображаемое для пользователя — составьте шаблон описания, которое увидит ваш клиент, когда клиент будет пополнять баланс. В шаблоне можно использовать переменные:

    • {amount} — сумма платежа
    • {agrmid} — идентификатор договора
    • {agrmnum} — номер договора
    • {email} — email клиента
    • {mobile} — мобильный телефон клиента
    • {agrnums} — номера договоров (если оплата по нескольким договорам)
    • {currency} — валюта (берется из параметра currency)

    Пример.

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

    При оплате пользователь увидит свои данные: Оплата 2 500 руб. по договору Contract_1

    image

  11. Минимальный размер платежа в личном кабинете — позволяет задать минимальную сумму, на которую ваши абоненты могут пополнить баланс. Если не хотите использовать это ограничение, укажите значение 0.

  12. Минимальный размер рекуррентного платежа — если вы работаете с автоплатежами, можно дополнительно задать минимальную сумму автооплаты.

    image

  13. Признак способа расчета — выберите признак, который будет присваиваться платежам, совершаемым через личный кабинет:

    • Полный расчет
    • Полная предоплата
    • Частичная предоплата
    • Аванс

  14. Признак предмета расчета — выберите предмет расчёта, который будет присваиваться платежам, совершаемым через личный кабинет:

    • Платёж
    • Товар
    • Услуга
    • Другое

  15. Название товара — введите наименование, которое будет подставляться в чек.

    image

  16. Описание автоплатежа, отображаемое для пользователя — текст, который будет отображаться для автоплатежей.

  17. URL, на который вернётся пользователь после подтверждения или отмены платежа — адрес страницы, на которую попадёт клиент после завершения оплаты.

    image

  18. Секретный ключ — ключ, который используется для идентификации сервиса в ЮKassa. Инструкция по генерации ключа.

    image

  19. Система налогообложения — выберите СНО оператора:

    • Общая
    • Упрощенная (доходы)
    • Упрощенная (доходы минус расходы)
    image

  20. Использовать обычную оплату — по умолчанию флаг установлен. Он отвечает за отображение кнопки «Оплата» в личном кабинете. Если хотите использовать только способ оплаты «СБП», снимите флаг.

  21. Использовать оплату по СБП — по умолчанию флаг установлен. Он отвечает за отображение кнопки «СБП» в личном кабинете. Если хотите использовать только обычный способ оплаты картой, снимите флаг.

    image

  22. Сохраните настройки ВПС.

    image

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

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

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

  1. Скопируйте файл kassa.py в директорию исполняемых скриптов вашего веб-сервера:

    cp /usr/local/billing/payments/yandex/kassa.py /var/www/cgi-bin/

    ``

  2. Укажите в файле настройки доступа. Пример:

    # Настройки логирования
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

    ``

  3. Сделайте скрипт исполняемым:

    chmod +x /var/www/cgi-bin/kassa.py

    ``

  1. Скопируйте файл kassa.py в директорию исполняемых скриптов вашего веб-сервера:

    cp /usr/local/billing/payments/yandex/kassa.py /usr/lib/cgi-bin/

    ``

  2. Укажите в файле настройки доступа. Пример:

    # Настройки логирования
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

    ``

  3. Сделайте скрипт исполняемым:

    chmod +x /usr/lib/cgi-bin/kassa.py

    ``

  1. Скопируйте файл kassa.py в директорию исполняемых скриптов вашего веб-сервера:

    cp /usr/local/billing/payments/yandex/kassa.py /usr/local/www/apache24/cgi-bin/

    ``

  2. Укажите в файле настройки доступа. Пример:

    # Настройки логирования
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

    ``

  3. Сделайте скрипт исполняемым:

    chmod +x /usr/local/www/apache24/cgi-bin/kassa.py

    ``

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

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

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

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

  2. Скопируйте скрипт kassa_recurrent_payment.py в директорию /usr/local/billing/pymodules/:

    cp /usr/local/billing/payments/yandex/kassa_recurrent_payment.py /usr/local/billing/pymodules/

    ``

  3. Укажите в файле настройки доступа. Пример:

    MANAGER = 'super_pay'
PASSWORD = '12345'
OPER_ID = 1

    ``

  4. Перезапустите модуль LBcore. Команды различаются в разных ОС.

    systemctl restart lbcore

    service lbcore restart

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

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

  1. Откройте файл конфигурации yooKassa.ini:

    nano /etc/lanbilling/phpclient/client/yooKassa.ini

    ``

    Включите платёжную систему в личном кабинете абонентов LANBilling:

    [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 отвечает за отображение кнопки «Оплата» в личном кабинете.

      • true — клиенты смогут использовать обычную оплату картой.
      • false — клиенты не смогут использовать обычную оплату картой.

    • useSbpPayment — отвечает за отображение кнопки «СБП» в личном кабинете.

      • true — клиенты смогут оплачивать услуги по СБП.
      • false — клиенты не смогут оплачивать услуги по СБП.

  1. Сохраните конфигурационный файл. Сериализуйте изменения:

    /usr/local/sbin/lbwebcfg -y client /etc/lanbilling/phpclient/client/

    ``

  1. Откройте файл конфигурации yooKassa.ini:

    nano /usr/local/etc/lanbilling/phpclient/client/yooKassa.ini

    ``

    Включите платёжную систему в личном кабинете абонентов LANBilling:

    [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 — предоплата 100%
      • partial_prepayment — предоплата
      • advance — аванс

    • minPaymentAmount — позволяет задать минимальную сумму, на которую ваши абоненты могут пополнить баланс. Если не хотите использовать это ограничение, укажите значение 0.

    • useCardPayment отвечает за отображение кнопки «Оплата» в личном кабинете.

      • true — клиенты смогут использовать обычную оплату картой.
      • false — клиенты не смогут использовать обычную оплату картой.

    • useSbpPayment — отвечает за отображение кнопки «СБП» в личном кабинете.

      • true — клиенты смогут оплачивать услуги по СБП.
      • false — клиенты не смогут оплачивать услуги по СБП.

  1. Сохраните конфигурационный файл. Сериализуйте изменения:

    /usr/local/sbin/lbwebcfg -y client /usr/local/etc/lanbilling/phpclient/client/

    ``

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

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

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

Соответствие ставок НДС их значениям в API:

  • Без НДС — 1
  • НДС 0% — 2
  • НДС по ставке 10% — 3
  • НДС по ставке 20% — 4
  • НДС по расчетной ставке 10/110 — 5
  • НДС по расчетной ставке 20/120 — 6
  • НДС по ставке 5% — 7
  • НДС по ставке 7% — 8
  • НДС по расчетной ставке 5/105 — 9
  • НДС по расчетной ставке 7/107 — 10

Параметр чека отправляется в структуре receipt->items->vat_code –>