Как настроить платёжную систему или подключить новую?

Введение
Добавление настроек

Синхронизация asr_fiscal и asr_cabinet и проверка.

Обработчик запроса платежа
Шаблон формы запроса платежа
Обработчик уведомлений

Параметры dbwork обработчика уведомлений
Результат работы dbwork обработчика уведомлений

Отладка обработчика уведомлений
Добавление формы платежа в Личный кабинет
Настройка мерчанта платежной системы
Отправка чеков в налоговую по ФЗ-54

Введение

Биллинг позволяет создавать и подключать модули для работы с новыми платежными системами (далее - ПС) в Личном кабинете абонента. Поддерживается классическая схема взаимодействия:

пользователь (абонент) указывает сумму и отправляет запрос на оплату в ПС;
пользователь производит оплату на сайте ПС;
сервер ПС уведомляет биллинг о результатах платежа;
биллинг фиксирует приход средств и пополняет баланс пользователя.

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

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

Ниже представлено подробное описание каждого из этих шагов.

Добавление настроек

Обычно, при создании запроса на оплату, платежные системы требуют передачи дополнительных данных - ID магазина, тип валюты, секретное слово и т.п. Эти данные удобнее всего добавлять и редактировать через администраторский сайт биллинга. Кнопка "Платежные системы" на главной странице администраторского сайта открывает интерфейс настройки всех подключенных ПС.

Чтобы добавить настройки для новой платежной системы в этот интерфейс, необходимо отредактировать файл /app/asr_fiscal/cfg/config, добавив в него аналогичный блок (пример для системы Elexnet):

declare -A elexnet
elexnet['widget']='menu "Настройка Elexnet" "Настройка Elexnet"'
elexnet['enable']='1'
elexnet['enable.widget']='checkbox "Включить Elexnet" "Включить Elexnet"'
elexnet['username']=''
elexnet['username.widget']='inputbox "Имя пользователя" "Имя пользователя"'
elexnet['password']=''
elexnet['password.widget']='inputbox "Пароль" "Пароль"'
elexnet['cabinet']='enable username password'

Ниже рассмотрим какие параметры для чего нужны.

declare -A elexnet

В первой строке задается системное имя вашей ПС (в примере - elexnet), далее определяется массив с этим же именем.

elexnet['widget']

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

elexnet['enable'], elexnet['enable.widget'], username, password и тд

Далее идет перечисление параметров, которые будут доступны для изменения через интерфейс настройки ПС в биллинге. Для каждого параметра можно указать значение по-умолчанию, например cтрока:

elexnet['enable']='1'

создает параметр "enable" со значением по-умолчанию равным единице. Следующая строка:

elexnet['enable.widget']='checkbox "Включить Elexnet" "Включить Elexnet"'

говорит, что параметр "enable" будет использовать для настройки виджет типа checkbox (галочка), т.е. принимать значения 0 или 1. Далее задается название поля (виджета) и текст подсказки, выводимой под ним. Для настройки текстовых параметров можно использовать виджет inputbox.

elexnet['cabinet']

Последняя строка elexnet['cabinet'] определяет какие из перечисленых параметров будут экспортированы в asr_cabinet, чтобы их можно было использовать в обработчике запросов платежей Payment.php
/app/asr_cabinet/cfg/fiscal.json

Синхронизация asr_fiscal и asr_cabinet и проверка.

После сохранения файла:

Синхронизируйте настройки asr_cabinet и asr_fiscal
```
chroot /app/asr_cabinet python /usr/local/bin/get_fiscal_config.py
```
Войдите в биллинг, затем в раздел "Платежные системы" (желтая плитка на главной странице биллинга) и проверьте, что поля для настройки вашей ПС были добавлены.

Обработчик запроса платежа

Личный кабинет использует общий обработчик запроса для всех платежных систем. Вам необходимо добавить в него условия для вашей платежной системы.

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

Изменения в модуле не нужны, если абонент оплачивает без захода в личный кабинет: платёжный терминал, банковское приложение, сайт платёжной системы.

Работа с файлом похожам на работу с кастомным модулем личного кабинета.

Файл размещается по пути /app/asr_cabinet/usr/local/lib/cabinet_modules/modules/Payment.php

Внутри файла определен класс Payment. В метод initData() необходимо добавить блок, получающий параметры из конфига (см. выше) и передающий их в шаблон формы запроса платежа.

Пример кода:

// если это наша платежная система
if($this->options['operator'] == 'elexnet'){
    // получим из конфига (см. выше) значения параметров user_name и password
    // и передадим их в шаблон формы запроса платежа
    $this->data['username'] = $this->fiscal_config->elexnet["username"][0];
    $this->data['password'] = $this->fiscal_config->elexnet["password"][0];
    // укажем название шаблона формы
    $this->template_name = 'Payment_elexnet';
}

Код для вашей ПС будет выглядеть аналогично.
Когда модуль будет готов, его необходимо скопировать в каталог хранения:

/app/asr_cabinet/var/cabinet_modules/

Так пользовательский модуль не исчезнет во время обновления, а также попадёт в бекап личного кабинета.

Внимание! Файлы из каталога хранения затирают более старые файлы в рабочем каталоге (для того, чтобы можно было заменять стандартные модули)

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

Шаблон формы запроса платежа

На предыдущем шаге мы определили название шаблона:

$this->template_name = 'Payment_elexnet';

Для создания шаблона необходимо добавить файл с указанным именем и расширением .php в папку: /app/asr_cabinet/usr/local/lib/cabinet_modules/modules/tpls/

Для примера выше файл будет называться Payment_elexnet.php.

Внутри файла должен быть добавлен HTML-код формы запроса платежа (см. документацию ПС для подробностей). Параметры, полученные из конфига (см. предыдущий шаг), будут доступны в шаблоне из массива $data. Например, в предыдущем шаге мы получили из конфига значение "username":

$this->data['username'] = $this->fiscal_config->elexnet["username"][0];

Вывести его в шаблоне можно так:

<?php echo $data['username']; ?>

Обработчик уведомлений

Обработчик для каждой платежной системы размещается в отдельном файле. URL этого файла в дальнейшем указывается в настройках мерчанта платежной системы. Файл будет принимать от ПС уведомления о совершенных платежах.

Файлы обработчиков, доступных по протоколу HTTPS, размещаются в папке /app/asr_fiscal/usr/local/www/htdocs/
Если платежная система требует, чтобы обработчик уведомлений был доступен по протоколу HTTP (без SSL), то разместить его нужно в папке /app/asr_fiscal/usr/local/www/htdocs/http

Название файла должно соответствовать названию платежной системы, например elexnet.php.

Внутри файла необходимо определить класс, наследуемый от системного класса PayWork. В классе нужно определить метод print_result() и добавить его вызов. Пример скелета файла:

<?php

include_once '/usr/local/www/include/pay_work.php';

class Elexnet extends PayWork {

    public function print_result() {

        // здесь размещается логика обработки платежа

    }

}

$paywork = new Elexnet($_REQUEST, 'Elexnet');
$paywork->print_result();

Внутри метода print_result() добавьте логику, необходимую для обработки ответов от платежной системы. Входящие параметры (GET и POST) доступны в методах класса через массив $this->params. Для окончательного принятия платежа биллингом необходимо заполнить поля класса - ACT, PAY_ID, SUMMA - и затем вызвать метод dbwork():

// Заполняем необходимые поля
$this->ACT = "PAY"; // всегда PAY для принятия платежа
$this->PAY_ID = $this->params['order_id'|'order_id']; // ID заказа, переданный от ПС
$this->SUMMA = $this->params['amount']; // сумма заказа

// Отмечаем оплаченный приход, после чего деньги будут зачислены на баланс абонента
$this->dbwork();

Чтобы обработчики сохранялись при обновлении, необходимо размещать их в /var/www/custom_htdocs и /var/www/custom_http, тогда в платёжной системе указывать URL не http://strana-telekom.ru:1444/elexnet.php, а http://strana-telekom.ru:1444/custom_http/elexnet.php или https://strana-telekom.ru:1443/custom_htdocs/elexnet.php

Параметры dbwork обработчика уведомлений

Параметр обработчика уведомлений ACT

Указывает на необходимое действие с платежом

CHECK - проверка доступности пополнения счета и статуса транзакции.
CHECK_ABONENT - проверка доступности пополнения счета без проверки транзакции.
ADD - создание транзакции. В ответе содержит идентификатор транзакции, по этому PAY_ID нужно будет совершать остальные действия.
PAY - подтверждение транзакции, пополняет счёт абонента.
CANCEL - отмена транзакции, сторнирование пополнения.

Другие параметры обработчика

PAY_ID - поле ID заказа, идентификатор транзакции в системе биллинга.
ACCOUNT - поле для поиска абонента. Содержимое должно соответствовать настройкам из статьи "поле для идентификации абонента". Если заказ был ранее создан в личном кабинете или методом ADD, то можно не указывать.
SUMMA - сумма заказа. Если заказ был ранее создан в личном кабинете или методом ADD, то можно не указывать.
OPERATOR_DATE - время операции, по умолчанию текущее.
PREVENT_SUBMIT_CHECK - флаг для отключения отправки чеков. Используется для платёжных систем с собственной отправкой чеков.
DATE_FROM - Фильтр даты для получения списка транзакций в команде CHECK.
DATE_TO - Фильтр даты для получения списка транзакций в команде CHECK.

Результат работы dbwork обработчика уведомлений

Метод возвращает результат в виде массива, где под ключом res содержится код, а под ключом msg текстовое описание.

Коды обрабатываются в методе prepare_result(), по умолчанию следующие:

0 - OK, успешно.
20 - Платеж уже проведен, возвращаем старые данные. Транзакция была подтверждена ранее. Код 20 превращается в код 0 в методе prepare_result.
20 - Сумма дублирующего платежа не совпадает с оригиналом. Транзакция была подтверждена ранее, но сумма в ней отличается от суммы, переданной в текущем запросе. Код 20 превращается в код 0 в методе prepare_result.
20 - Дата дублирующего платежа не совпадает с оригиналом. Транзакция была подтверждена ранее, но дата в ней отличается от даты, переданной в текущем запросе. Код 20 превращается в код 0 в методе prepare_result.
51 - Не указан параметр для поиска абонента. Нужно указать хотя бы один параметр для поиска абонента. Код 51 превращается в код 4 в методе prepare_result.
52 - В платеже не указана сумма. Код 52 превращается в код 7 в методе prepare_result.
52 - User is deleted. Абонент найден, но удалён в коризну. Код 52 превращается в код 7 в методе prepare_result.
52 - User or group is disabled. Абонент найден, но заблокирован администратором или в системной блокировке. Код 52 превращается в код 7 в методе prepare_result.
53 - Абонент не найден. Код 53 превращается в код 5 в методе prepare_result.
71 - Неизвестный оператор. Нужно передать имя платёжной системы.
73 - Неизвестная команда. Нужно указать корректный параметр ACT.
81 - Невозможно получить старые данные. Транзакция была подтверждена ранее, но не удаётся получить данные из соответствующей финансовой операции.
99 - Неизвестная ошибка. Код 99 превращается в код 300 в методе prepare_result.
102 - Транзакции не существует. Код 102 превращается в код 0 в методе prepare_result.
202 - Транзакция уже отменена.
300 - Неизвестная ошибка. Все неизвестные коды превращаются в код 300 в методе prepare_result.

Отладка обработчика уведомлений

Класс PayWork предоставляет методы для логирования:

$this->log->log_it('Hello world');

Добавленные таким образом записи будут сохранены в лог /app/asr_fiscal/var/log/paysystems/название_обработчика.log

Добавление формы платежа в Личный кабинет

Для того, чтобы ваша платежная система стала доступна для абонентов в Личном кабинете, необходимо создать новую страницу Wordpress в админке сайта провайдера:

Перейдите по адресу http://ваш-сайт/admin и войдите в админку Wordpress;
В боковом меню выберите "Личный кабинет" -> "Все страницы";
Откройте страницу "Оплата";
Добавьте в текст страницы заголовок и шорт-код для вашей платежной системы, например:

Оплата через Elexnet
[cabinet_payment operator=elexnet|cabinet_payment operator=elexnet]

Шорт-код cabinet_payment принимает аргумент operator, в котором необходимо передать название вашей платежной системы (см. раздел "Обработчик запроса платежа" выше).

Настройка мерчанта платежной системы

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

URL имеет следующий формат:

http://{ваш-сайт}:1444/{название_обработчика_платежей}.php

например:

http://strana-telekom.ru:1444/elexnet.php

Отправка чеков в налоговую по ФЗ-54

По-умолчанию чеки по онлайн платежам отправляются в налоговую если настроена интеграция с онлайн-кассами.
Если Ваша платёжная система сама отправляет чеки, Вы можете добавить её в список исключений. Для этого укажите operator_name ("Payment_elexnet" из примера выше) платёжной системы в конфигурационном файле /app/asr_fiscal/cfg/config в опцию "no_cheque_for". Если платёжных систем несколько, перечислите их идентификаторы через пробел, например:

app['no_cheque_for']='Payment_elexnet OSMP_custom'