Введение
Биллинг позволяет создавать и подключать модули для работы с новыми платежными системами (далее - ПС) в Личном кабинете абонента. Поддерживается классическая схема взаимодействия:
- пользователь (абонент) указывает сумму и отправляет запрос на оплату в ПС;
- пользователь производит оплату на сайте ПС;
- сервер ПС уведомляет биллинг о результатах платежа;
- биллинг фиксирует приход средств и пополняет баланс пользователя.
Для подключения и использования новой платежной системы в Личном кабинете биллинга необходимо выполнить следующие шаги:
- добавить поля для настройки платежной системы через администраторский сайт биллинга;
- добавить обработчик запроса платежа;
- добавить шаблон формы запроса платежа;
- добавить обработчик уведомлений от платежной системы;
- добавить страницу с формой платежа в Личный кабинет;
- настроить мерчант платежной системы.
Ниже представлено подробное описание каждого из этих шагов.
Добавление настроек
Обычно, при создании запроса на оплату, платежные системы требуют передачи дополнительных данных - 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'; }
Код для вашей ПС будет выглядеть аналогично.
Шаблон формы запроса платежа
На предыдущем шаге мы определили название шаблона:
$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();
Отладка обработчика уведомлений
Класс 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'