1. Настройка взаимодействия Яндекс.Кассы с Eltex Captive Portal

1.1 Настройка общих параметров

В версии программного обеспечения 1.13 оплата доступна при работе с точками доступа и не доступна в режиме работы через BRAS.

Для настройки взаимодействия необходимо зайти в Конструктор порталов по ссылке http://<ip-сервера>:8080/epadmin/ . В разделе «Настройка БД платежей» активировать чекбокс «Использовать БД платежей» и изменить остальные настройки, если это необходимо.

Активация чекбокса «Использовать БД платежей» отвечает за корректное восстановление платежей при рестарте портала и за корректное удаление «протухших» незаконченных платежей.

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

ShopId можно получить после регистрации на Яндекс.Кассе, ShopPassword нужно придумать самостоятельно (лучше не делать больше, чем 20 символов) в аккаунте на Кассе, номер витрины Яндекс.Касса пришлёт в письме после подписания договора (подробнее про регистрацию в главе 4. Регистрация на Яндекс.Кассе).

Демо-режим оплаты используется на ранних стадиях взаимодействия с Яндекс.Кассой после того, как договор подписан. В это время все платежи виртуальны и производятся через тестовый аккаунт Яндекс.Кошелька и тестовую банковскую карту, реквизиты предоставляет Яндекс.Деньги. Обе стороны (инженер клиента сервиса и Яндекс.Касса) производят проверку, что платежи проходят, уведомления приходят, реестры платежей приходят на почтовый адрес с полным списком совершённых платежей. Подробнее про реестры в главе 3 пункте 3.3. Получение ежедневного реестра.

Необходимо учитывать, что Яндекс «выпускает» в реальный режим только после того, как клиент уведомит Яндекс.Деньги (своего менеджера) об успешных платежах из демо-режима.

Также необходимо активировать способы оплаты, которые затем будут доступны клиентам. Проверить доступные для договора способы можно в личном кабинете на Яндекс.Кассе в разделе «Договор».

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

1.2 Создание тарифов

1.2.1 Создание тарифного плана через Eltex.EMS

Чтобы создать тарифный план, зайдите в меню «RADIUS/управление тарифными планами», нажмите кнопку «Добавить». Задайте основные параметры: название, код, домен. Чтобы тариф был виден на портале, необходимо установить флаг «Портальная аутентификация».

Также необходимо сделать тариф платным, для этого укажите «Стоимость услуги»:

1.2.2 Создание тарифного плана через Eltex Личный кабинет B2B

Для создания тарифного плана через Личный кабинет на вкладке «Сервисы и тарифы» нужно нажать кнопку «Добавить» и создать тариф с портальной аутентификацией и оплатой:

1.3 Настройка сервиса белых адресов eltex-apb

Для работоспособности системы оплаты необходимо настроить списки белых IP адресов, которые позволят пользователю переходить на сайты оплаты еще до регистрации. Для этого используется APB сервис.

Скопируйте списки командой:

cp /etc/eltex-apb/hosts_kassa.json /etc/eltex-apb/hosts.json

Выполните перезапуск сервиса:

service eltex-apb restart

Проверьте, что сервис запустился:

root@swlc:/home/tester# ps ax | grep apb
10286 ?        Ssl    0:12 /usr/bin/java -Xms128m -Xmx2048m -Dlog4j.configurationFile=file:/etc/eltex-apb/log4j2.xml -Dorg.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.Slf4jLog -jar /usr/share/eltex-apb/apb.jar -p 8090 -q 0 -M524288

Далее необходимо настроить адрес сервиса на каждой точке доступа. Откройте вкладку «Конфигурация/Captive Portal. Global». В поле «Roaming Service URL» введите адрес в формате:

ws://<IP address SoftWLC>:8090/apb/broadcast

После того, как всё настроено и на ТД настроен SSID, пользователь может совершить оплату.

2. Процесс оплаты: действия пользователя и портала

2.1 Обобщенная схема

Обобщённый алгоритм оплаты и взаимодействия с платёжным сервисом выглядит следующим образом:

2.2 Детальный алгоритм оплаты

1. После подтверждения учётной записи пользователь выбирает платный тариф.

2. После выбора тарифа пользователь попадает на страницу выбора способа оплаты

В это время на стороне портала происходит запись первичных данных в БД платежей: В БД платежей существует 2 таблицы, почти полностью дублирующие друг друга: активные платежи и логи платежей. Их поля приведены выше. При записи первичных данных записывается: номер телефона, дата начала регистрации на портале, параметры от ТД (начинаются с x_eltex_cp), тарифный код и цена, флаг создания аккаунта (f_account_created) и флаг отправки смс (f_sms_ok). Остальные флаги не определены (состояние = -1).

3. Пользователь выбирает способ оплаты, и в зависимости от выбранного способа происходит его перенаправление на одну из страниц платёжного сервиса.

Рассмотрим случай, когда выбран Яндекс.Кошелёк.

2.2.1 Оплата через Яндекс.Кошелёк

При выборе Яндекс.Кошелька как способа оплаты, если пользователь ранее не авторизовался в своём Кошельке, ему будет предложено авторизоваться (капча вводится только в демо-режиме):

После авторизации пользователю будет предложено подтвердить детали платежа, и, возможно, ввести платёжный пароль в зависимости от настроек Кошелька пользователя:

После того, как пользователь нажал кнопку «Подтвердить», начинается взаимодействие сервиса Яндекс.Кассы и портала. Яндекс.Касса присылает на портал уведомление «Проверка заказа». Портал проверяет валидность уведомления по md5-хэшу, который приходит как один из параметров уведомления, сравнивая со своим хэшем, рассчитанным по полученным параметрам и ShopPassword. Также портал может проверять адрес, с которого пришло уведомление. После проверки хэша происходит проверка суммы, и если она верна и все проверки пройдены, портал отвечает Яндекс.Деньгам «ОК».

Если же что-то не так, то портал отвечает Яндекс.Деньгам «Не ОК», деньги у пользователя не снимаются, пользователю будет показана страница Яндекс.Денег с надписью в стиле «Что-то пошло не так», и по нажатию ссылки на этой странице «Вернуться в магазин» пользователь будет возвращён на страницу получения пароля на портале.

Если на 1ое уведомление Яндекс.Деньгами был получен ответ «ОК», то тогда Яндекс.Деньги присылает уведомление о совершённом платеже. Это уведомление также проверяется на валидность по хэшу, проверяется сумма. Если все проверки пройдены успешно, портал отвечает Яндекс.Деньгам «ОК». Если что-то не так, можно ответить «Не ОК», и тогда деньги будут возвращены пользователю.

В то время, когда приходят уведомления, портал записывает информацию из них в БД Платежей: состояние флагов — валидны ли уведомления, время уведомлений, детали платежа: id транзакции в сервисе Яндекса, тип платежа, сумму с комиссией и без, номер клиентского счёта (если используется Яндекс.Кошелёк), номер аккаунта на Кассе, на который производится оплата и прочие параметры.

Таким образом, платёж в БД после двух успешных уведомлений будет выглядеть следующим образом:

На рисунке видно, что определены флаги проверок уведомлений (f_check_order_ok, f_notification_valid), время уведомлений, а также данные от платёжного сервиса (названия пунктов начинаются с ps).

Если оба уведомления валидны, то в атрибут БД Radius записывается, что пользователь оплатил услугу.

В случае успешного платежа Яндекс.Деньги покажет страницу с надписью, что «Платёж успешно завершён»:

Внизу страницы, показанной на рисунке выше, есть ссылка «Вернуться на сайт магазина». При нажатии на ссылку пользователь вернётся на портал на страницу успешного подключения.

На портале с некоторой периодичностью работает монитор, переносит устаревшие записи из активных платежей в логи платежей.

2.2.2 Оплата с помощью банковской карты

Если на шаге 3 выбран способ оплаты через банковскую карту, то пользователь увидит следующую страницу:

На данной странице пользователю также предлагается ввести e-mail, на который Яндекс.Деньги уведомит пользователя об оплате.

После того, как все данные заполнены и нажата кнопка заплатить, пользователь увидит страницу, предупреждающую, что сейчас пользователь будет направлен на сайт банка для ввода 3-D Secure пароля его карты:

Далее пользователь вводит 3-D Secure пароль на открывшейся странице, и далее всё происходит аналогично пунктам 6-8 из сценария платежа посредством Яндекс.Кошелька.

3. Дополнительные возможности

3.1 Логирование информации по оплатам

Все действия в рамках оплаты фиксируются отдельным уровнем лога — PAY, поэтому существует отдельный файл — pay_ep.txt, в котором собрана вся информация по платежам, фиксируются попытки записать информацию по платежу в базу. Соответственно, эти логи архивируются по тому же принципу, по которому архивируются остальные логи решения.

3.2 Получение ежедневного реестра

Яндекс.Касса предоставляет возможность получать ежедневные выписки на электронную почту о совершённых платежах вида:

Можно сравнивать список в реестре со списком в БД Платежи.

3.3 Статистика

По требованию может быть реализован подсчёт статистики по платежам на основе данных из БД Платежи.

4. Регистрация на Яндекс.Кассе

Для того, чтобы начать пользоваться необходимо совершить несколько шагов.

4.1 Технические детали

1. Необходимо создать у себя внешний домен, на который Яндекс.Касса будет присылать уведомления.

2. Для данного домена необходимо получить SSL сертификат и ключ для него, подтверждённый СА (уведомления от Кассы приходят только по https),  и поместить их на сервер.

3. После добавления сертификата и ключа на сервер, пропишите путь до них в nginx.  Для этого в файле /etc/nginx/conf.d/softwlc.conf раскомментируйте следующие строки и укажите путь до файлов:

# SSL configuration
listen 8443 ssl;
listen [::]:8443 ssl;
gzip off;

ssl_certificate "/etc/letsencrypt/live/radius.eltex.nsk.ru/fullchain.pem";
ssl_certificate_key "/etc/letsencrypt/live/radius.eltex.nsk.ru/privkey.pem";

server_name radius.eltex.nsk.ru ;

3. Для того, чтобы уведомления успешно приходили, необходимо открыть входящие соединения для порта 8443 (или ваш номер порта) для адресов, которые необходимо уточнить у технической поддержки Яндекс.Денег.

4.2 Регистрация на Яндекс.Кассе

1. Необходимо подключить Кассу. Для этого перейдите на официальный сайт Яндекс.Кассы https://kassa.yandex.ru/ и нажмите на кнопку "Подключить Кассу".  После нажатия кнопки будет доступна форма для регистрации организации, а также создания аккаунта на Кассе.

2. После заполнения параметров первой формы необходимо заполнить параметры в самом аккаунте. Необходимо выбрать интеграцию по протоколу http, а на странице настройки урлов заполнить их определённым образом:

Сайт магазина: указать страницу Вашего сайта, при этом домена Вашего сайта не должно быть в списке разрешённых адресов в EMS, чтобы обеспечить возврат на портал после оплаты, например, через терминалы (будет работать редирект на портал, так как адреса не будет в разрешённых).

сheckURL: https://portal_domain:port/eltex_portal/ya-check-order, где portal_ domain — адрес домена, на который будут приходить уведомления, port — в случае, если используется прокидывание портов.

paymentAvisoURL: https://portal_domain:port/eltex_portal/ya-payment-aviso

successURL и failURL: динамические.

При заполнении данных в аккаунте, например, в секции «Настройки», необходимо учитывать, что поля редактируемы только в первый раз, после сохранения настроек для их смены необходимо писать менеджерам Яндекс.Денег.

3. В аккаунте есть страница «Договор» – необходимо его заключить с Яндекс.Кассой. Заключение договора занимает некоторое время и может произойти быстрее, если напомнить менеджерам Кассы о своей заявке в письме.

4. После заключения договора менеджер Яндекс.Деньег пришлёт shopId, scid — их нужно будет заполнить на портале в Конструкторе Порталов, как было показано в начале документации. ShopPassword нужно придумать самим, длина пароля не более 20 символов — и заполнить в настройках в аккаунте на Яндекс.Кассе.

5. В процессе взаимодействия менеджеры могут прислать техническую анкету, в которой снова будет запрос урлов, которые ранее были заполнены в аккаунте на Кассе. Однако в анкете урлы будут делиться на урлы для уведомлений и для реальных — они могут быть одинаковыми, хотя в анкете может быть сказано, что не могут.

6. Сначала будет доступен демо-режим, потом Яндекс.Деньги переводят в реальный, но через проверку их службой безопасности. В демо предоставляют доступ к тестовому аккаунту Яндекс.Кошелька, дают реквизиты тестовой банковской карты. При переходе в реальный режим потребуется донести до менеджеров Яндекс.Кассы, что используется схема с участием оборудования.

4.3 Ссылки на ресурсы Яндекс.Кассы

Подробная инструкция по интеграции, в том числе информация по первым шагам и регистрации: https://tech.yandex.ru/money/doc/payment-solution/shop-config/intro-docpage/
Вопросы и ответы https://money.yandex.ru/doc.xml?id=526382
Тарифы представлены на странице: https://kassa.yandex.ru/fees/
Описание протокола приема платежей для магазинов: https://tech.yandex.ru/money/doc/payment-solution/About-docpage/

5. Кейсы при эксплуатации

Если при настройке портала администратор указал номер(а) техподдержки, могут возникнуть обращения пользователей.

5.1 Примерные действия специалиста технической поддержки при обращении пользователя

5.1.1 Пользователь оплатил, но не получил доступа

Специалисту технической поддержки необходимо попросить пользователя назвать его номер телефона, а также, по возможности, id операции, который будет в большинстве случаев показан пользователю в случае неудачи.

По данным номерам необходимо посмотреть информацию в личном кабинете на Яндекс.Кассе: в разделе «Операции» по номеру телефона или id, названному пользователем, можно найти платёж и посмотреть его статус: создан или зачислен. Статус отображается при наведении на кружок рядом с платежом. Если кружок и стрелка зелёные — значит, оплачено, если серые — не оплачено. Созданный платёж не обязательно оплачен.

Если с платежом всё в порядке, однако доступа к Интернет пользователь не получил, необходимо по номеру телефона посмотреть информацию о платеже в таблице stored_payments и посмотреть, в порядке ли информация по флагам:

-1 означает отсутствие информации по флагу;

 0 — не валидно;

 1 — валидно.

Выборку в таблице stored_payments можно делать по полю id_cp — его значение отображается в личном кабинете рядом с надписью «Ваш ID».

В данной записи все флаги валидны.

Если какой-то из четырёх флагов не имеет значения 1, значит, в системе он не считается оплаченным, необходимо консультироваться с техподдержкой Eltex.

5.1.2 Оплата с банковской карты пользователя недоступна

Сначала специалист технической поддержки должен уточнить, что именно страница для ввода 3d-secure-пароля не грузится, а не банк отказывает в транзакции по этой карте, хотя страница для ввода 3d-secure-пароля грузится нормально. Если действительно не грузится страница, необходимо поблагодарить пользователя за сообщение, попросить воспользоваться другим способом, а также пообещать передать информацию разработчикам решения.

5.2 Технические кейсы

5.2.1 Вынужденная полная переустановка пакета eltex-portal-mysql

Записать себе значение id последней записи в таблице активных платежей. Удалить пакет через apt-get purge. Поставить через dpkg -i. Задать начальное значение id в активных платежах на единицу большее записанного.

Пояснение:

Id платежа в активной таблице сохраняется в таблицу логов как id_cp и является уникальным идентификатором номера заказа на портале. Этот параметр передаётся на Яндекс.Кассу. Если по данному номеру заказа платёж уже был совершён, Яндекс.Касса не позволит заново провести платёж. Исходя из этого, необходимо контролировать, чтобы при переустановке пакета eltex-portal-mysql id в таблице активных платежей начинались с последнего значения, на котором остановились, а не 1. Изменить начальное значение для id на значение, равное n, можно следующей командой:

alter table active_payments auto_increment=n;