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

{toc:maxLevel=3}

h2. Введение

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

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

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

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

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

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

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

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

{code:language=bash}
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'
{code}

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

h4. declare \-A elexnet

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

h4. elexnet\['widget'\]

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

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

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

{code:language=bash}
elexnet['enable']='1'
{code}

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

{code:language=bash}
elexnet['enable.widget']='checkbox "Включить Elexnet" "Включить Elexnet"'
{code}

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

h4. elexnet\['cabinet'\]

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

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

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

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

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

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

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

Работа с файлом похожам на работу с [кастомным модулем личного кабинета|CarbonBilling:Пользовательские модули в cabinet_modules].

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

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

Пример кода:

{code:language=php}
// если это наша платежная система
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';
}
{code}

Код для вашей ПС будет выглядеть аналогично.
Когда модуль будет готов, его необходимо скопировать в каталог хранения:
{code}/app/asr_cabinet/var/cabinet_modules/{code}

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

{note}
{color:#ff0000}{*}Внимание\!*{color} Файлы из каталога хранения затирают более старые файлы в рабочем каталоге (для того, чтобы можно было заменять стандартные модули)

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


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

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

{code:language=php}
$this->template_name = 'Payment_elexnet';
{code}

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

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

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

{code:language=php}
$this->data['username'] = $this->fiscal_config->elexnet["username"][0];
{code}

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

{code:language=php}
<?php echo $data['username']; ?>
{code}


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

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

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

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

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

{code:language=php}
<?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();
{code}

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

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

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

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

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

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

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

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

h3. Результат работы 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*.

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

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

{code:language=php}
$this->log->log_it('Hello world');
{code}

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


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

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

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

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

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


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

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

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

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

например:

{code}
http://strana-telekom.ru:1444/elexnet.php
{code}

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

По-умолчанию чеки по онлайн платежам отправляются в налоговую если настроена интеграция с [онлайн-кассами|Онлайн-кассы (передача чеков ОФД по ФЗ-54)].
Если Ваша платёжная система сама отправляет чеки, Вы можете добавить её в список исключений. Для этого укажите _operator_name_ ("Payment_elexnet" из примера выше) платёжной системы в конфигурационном файле */app/asr_fiscal/cfg/config* в опцию "no_cheque_for". Если платёжных систем несколько, перечислите их идентификаторы через пробел, например:
{code}app['no_cheque_for']='Payment_elexnet OSMP_custom'{code}