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

Ключ
Эта строка удалена.
Это слово было удалено. Это слово было добавлено.
Эта строка добавлена.

Изменения (18)

просмотр истории страницы
Если система имеет свой протокол, то вам необходимо:
{toc:maxLevel=3}

1. Создать заявку в helpdesk.carbonsoft.ru
h2. Введение

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

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

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

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

6. Помогать в тестировании разработчику модуля.
Ниже представлено подробное описание каждого из этих шагов.

7. Провести окончательное тестирование и ввести в эксплуатацию.
h2. Добавление настроек

Обычно подключение новой платежной системы занимает от 2 недель до 1 месяца.
Обычно, при создании запроса на оплату, платежные системы требуют передачи дополнительных данных - 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();
{code}

h3. Параметры 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}