Платежные web-сервисы: Сервис интеграции с платежной системой Alfabank ATM (оплата через терминалы, кассы банка)

Версия статьи от 13-10-2023.

Поддерживаемые версии: Начиная с 2009.2.23.0 Начиная с 15.3

Введение

Данный модуль реализует возможность оплаты путёвок в ПК «Мастер-Web» через терминалы, банкоматы, кассы Альфа-банк.
Широкое распространение Альфа-банка позволяет предоставить возможность оплаты большому количеству пользователей. Особенно полезным данный модуль может быть туристическим компаниям, ориентированным на работу с частными клиентами.

Установка

Для установки дополнительного модуля Сервис интеграции с платежной системой Alfabank (АТМ) нужно создать директорию AlfabankTerminals в каталоге C:/inetpub/wwwroot (корневом каталоге IIS) и выложить туда распакованные файлы из архива
mw-AlfabankTerminals-9.2.23.ХХXXX.zip.

Создание виртуального каталога

По умолчанию корневым каталогом IIS является C:/Inetpub/wwwroot. Для создания виртуального каталога для приложения находящегося в этом каталоге нужно выполнить следующие действия:
1 Зайти в Пуск (Start) → Настройки (Settings) → Панель управления (Control Panel) → Администрирование (Administrative Tools)


2 Диспетчер служб IIS


3 В открывшемся дереве каталогов выбрать Web Sites – Default Web Site. В открывшемся списке найти папку, для которой нужно создать виртуальный каталог, кликнуть по ней правой кнопкой мыши и выбрать Преобразовать в приложение


4 В открывшемся окне нужно нажать кнопку ОК

Подключение к базе данных ПК «Мастер-Тур»

В файле web.config, расположенном в папке AlfabankTerminals пропишите необходимые параметры подключения (красным цветом выделены значения, которые необходимо ввести). Строка подключения к базе данных ПК «Мастер-Тур»:
<add key = "connectionString" value = "Data Source=ip-адрес сервера базы данных ПК «Мастер-Тур»;Initial Catalog=название базы данных ПК «Мастер-Тур»;User ID=логин пользователя ПК «Мастер-Тур»;Password=пароль пользователя ПК «Мастер-Тур»"/>

Настройка

Настройки задаются в секции <appSettings> файла web.config приложения AlfabankTerminals.

№	Описание	Значение	Настройка
1	ISO-код рубля. Настройка является обязательной!	ISO-код рубля, используемый в ПК «Мастер-Тур».	<add key="RubleCurrencyISOCode" value="RUB"/>
2	Настройка, определяющая дату, на которую должен подбираться курс валют для пересчета суммы к оплате.	FixationDate или отсутствие настройки - курс на дату последней фиксации путевки на момент совершения платежа, а если путевка не зафиксирована, то на дату совершения платежа; ConfirmDate — курс на дату последнего подтверждения заявки (если подтверждения путевки еще не было, либо курс на дату подтверждения не заведен, то будет отображаться курс на момент совершения платежа); OrderDate — дата оформления заявки; PaymentDate - курс на дату совершения платежа.	<add key="courseExchangeDate" value="orderdate"/>
3	Определяет тип платежной операции. Тип платежной операции так же может задаваться в настройке SYSPaymentOperationId в таблице SystemSettings. В таком случае в настройке PaymentOperationId задается название настройки из таблицы SystemSettings. Обязательная настройка.	Идентификатор типа операции - поле PO_Id из таблицы [PaymentOperations]. Либо название настройки SYSPaymentOperationId из таблицы [SystemSettings].	<add key="PaymentOperationId" value="1" />
4	Настройка, определяющая статусы путевок, при которых доступна возможность оплаты через систему электронных платежей Alfabank (ATM).	- ключи статусов из таблицы [Order_Status], при которых доступна оплата через систему электронных платежей. - отсутствие настройки - разрешена оплата путёвок только со статусом Ok .	<add key="paymentsStatuses" value="4,7" />
5	Настройка, позволяющая задавать размер комиссии (в виде коэффицента), которая будет включена в сумму размера задолженности по заявке.	Используется в методе Check Размер задолженности умножается на коэффициент, указанный в этой настройке(целая часть отделяется либо запятой, либо точкой).	<add key="ComissionCheck" value="1.03"/>
6	Настройка, позволяющая задавать размер комиссии (в виде коэффицента), которая будет включена в сумму оплаты.	Используется в методе Pay Размер путевки умножается на коэффициент, указанный в этой настройке(целая часть отделяется либо запятой, либо точкой).	<add key="ComissionPay" value="1.03"/>
7	Настройка, определяющая минимальный размер комиссии в валюте путевки.	Значение комиссии, которую необходимо включить в сумму оплаты (при проверке Check) или вычесть (при платеже Pay). (целая часть отделяется либо запятой, либо точкой).	<add key="MinComission" value="42"/>
8	Настройка, определяющая минимальный размер платежа в валюте путевки, для дальнейшего расчета комиссии.	Значение обязательно больше 0.(целая часть отделяется либо запятой, либо точкой). Отсутствие настройки или неуказанное значение по умолчанию равно 1. Если платёж больше MinPay, то будет использован параметр ComissionCheck либо ComissionPay. Если платёж меньше MinPay, то будет использован параметр MinComission.	<add key="MinPay" value="2000"/>
9	Определяет тип платежной системы при сохранении платежей. Информация о типе платежной системы записывается в историю по путевке. Для системы «Мастер-Финанс» информация записывается в столбец DP_PAYMENTSSYS таблицы [FIN_DOGOVOR_PAID]. Обязательная настройка.	Название платежной системы	<add key="PaymentSystem" value="AlfabankTerminals"/>
10	Включение режима записи нового платежа в систему «Мастер-Финанс». При этом в ПК «Мастер-Тур» платежи не сохраняются.	true - включена запись платежей в «Мастер-Финанс»; false или отсутствие настройки - выключает запись платежей в «Мастер-Финанс».	<add key="AddPaymentsToMasterFinance" value="true" /> В версиях до релиза 9222SP0 может использоваться старая настройка: <add key="paymentFactory" value="MasterSoft.Payments.PaymentFactoryWebPay, MasterSoft.Payments" />

Подготовка данных

Проверка заявок и проведение платежа через платежную систему в базу туроператора осуществляется по оформленным путевкам.

Работа в системе

Осуществляется 2 типа запросов:

• Pay - проведение платежа,
• Check - проверка состояния счёта Плательщика.

Запрос на проверку состояния счёта плательщика

Для проверки состояния Плательщика, система Банка генерирует запрос следующего вида:

https://localhost/AlfaTerminals/api/Pay?command=check&txn_id=1234567&account=DF21100001&sum=0.00&txn_date=20230815120133

Строка запроса содержит следующие обязательные переменные:

• command=check – запрос на проверку состояния Плательщика
  
• txn_id=1234567 – внутренний номер платежа в системе Банка
  
• account=DF21100001 – номер путевки в системе ПК "Мастер-Тур"
  
• sum=0.00 – Обязательный параметр. На текущий момент не обрабатывается. Представляет собой дробное число с точностью до сотых, в качестве разделителя используется «.» (точка).

Необязательные переменные:

• txn_date=20230815120133 – дата учета платежа в системе Банка, которая передаётся в формате ГГГГММДДЧЧММСС. Можно не указывать. Если не указана, то по умолчанию равна дате создания путевки. Данная дата также используется для расчета курса, если путевка в валюте.
  

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

<response xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <osmp_txn_id>1234567</osmp_txn_id> <result>0</result> <comment/> <amount>148139.25</sum> <inn>7701100000</inn> <rs>111111111111111100000000000000</rs> <bik>044525593</bik> <ks>30101.810.2.00000000593</ks> <name>Фирма-владелец</name> <bank_name>Тестовый банк</bank_name> <info>Дата начала тура: 17.04.2017</info> <fio>EGOROV I.</fio> </response>

Возвращаемые значения:

• <osmp_txn_id> - номер транзакции в системе Банка, который передается в запросе переменной txn_id.
• <result> - Код результата завершения запроса.
• <comment> - Необязательный элемент – комментарий завершения операции.
• <amount> - Оставшаяся сумма к оплате/ Представляет собой дробное число с точностью до сотых, в качестве разделителя используется «.» (точка).
• <inn> - ИНН Плательщика.
• <rs> - Расчётный счёт Плательщика.
• <bik> - БИК Банка Плательщика.
• <ks> - Кор. счёт Банка Плательщика.
• <name> - Наименование Плательщика.
• <bank_name> - Наименование банка Плательщика.
• <info> - Дополнительная информация.
• <fio> - Фамилия, имя главного туриста по путёвке.

Применение комиссий в методе Check

Сравниваем размер остатка по путевке со значением в настройке MinPay.
Если платёж больше, то отображается значение "Сумма Платежа, умноженная на коээфициент ComissionCheck.
Если платёж окажется меньше, то в отображается значение "Сумма Платежа минус MinComission".

Запрос на пополнение лицевого счёта плательщика

https://localhost/AlfabankTerminals/api/Pay?command=pay&txn_id=1234567&txn_date=20160815120133&account=DF21100001&sum=10.45

Строка запроса содержит следующие обязательные переменные:

• command=pay – запрос на пополнение баланса Плательщика
  
• txn_id=1234567 – внутренний номер платежа в системе Банка
  
• txn_date=20160815120133 – дата учета платежа в системе Банка, которая передаётся в формате ГГГГММДДЧЧММСС.
  
• account=DF21100001 – ключ путевки в системе ПК "Мастер_тур"..
  
• sum=10.45 – сумма к зачислению на лицевой счет Плательщика. Представляет собой дробное число с точностью до сотых, в качестве разделителя используется «.» (точка).
  

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

<response xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <osmp_txn_id>1234567</osmp_txn_id> <result>0</result> <comment/> <amount>10.45</sum> <prv_txn>56</prv_txn> </response>

Возвращаемые значения:

• <osmp_txn_id> - номер транзакции в системе Банка, который передается Клиенту в переменной txn_id
• <result> - код результата завершения запроса
• <comment> - необязательный элемент – комментарий завершения операции
• <amount> - сумма платежа. Представляет собой дробное число с точностью до сотых, в качестве разделителя используется «.» (точка).
• <prv_txn> - ключ платежа в системе ПК "Мастер-Тур" (Параметр Pm_Id из таблицы Payments).

Применение комиссий в методе Pay

Сравниваем размер платежа со значением в настройке MinPay.
Если платёж больше, то в базу данных ПК "Мастер-тур" записывается значение "Сумма Платежа, умноженная на коээфициент ComissionPay.
Если платёж окажется меньше, то в базу данных ПК "Мастер-тур" записывается значение "Сумма Платежа минус MinComission".

Коды завершения обработки запросов

При обработке запросов от системы Банка, сервис возвращает соответствующие коды в элементе <result>.

Код	Комментарий	Фатальность
0	ОК.	-
1	Временная ошибка. Повторите запрос позже.	-
4	Неверный формат идентификатора Плательщика	+
5	Идентификатор Плательщика не найден (Ошиблись номером)	+
7	Прием платежа запрещен провайдером	+
8	Прием платежа запрещен по техническим причинам	+
79	Счет Плательщика не активен	+
79	Счет Плательщика не активен	+
90	Проведение платежа не окончено	+
241	Сумма слишком мала	+
242	Сумма слишком велика	+
243	Невозможно проверить состояние счёта	+
300	Другая ошибка провайдера	+
301	Нет прав на проверку лицензии	+
302	Срок лицензии истек	+