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

Версия статьи от {{REVISIONDAY}}-{{REVISIONMONTH}}-{{REVISIONYEAR}}.
<table style="color:black; background-color:#ffffcc;" cellpadding="10" cellspacing="0" border="1">
<tr>
<td>
Поддерживаемые версии:<br />
Начиная с 2009.2.23.0<br />
Начиная с 15.3<br />
</td>
</tr>
</table>
<br />
==Введение==
Данный модуль реализует возможность оплаты путёвок в ПК «Мастер-Web» через терминалы, банкоматы, кассы '''Альфа-банк'''.<br> Широкое распространение Альфа-банка позволяет предоставить возможность оплаты большому количеству пользователей. Особенно полезным данный модуль может быть туристическим компаниям, ориентированным на работу с частными клиентами.<br />
==Установка== 
Для установки дополнительного модуля '''Сервис интеграции с платежной системой Alfabank (АТМ)''' нужно создать директорию '''AlfabankTerminals''' в каталоге <code>C:/inetpub/wwwroot</code> (корневом каталоге '''IIS''')  и выложить туда распакованные файлы из архива<br />
<code>mw-AlfabankTerminals-9.2.23.ХХXXX.zip</code>.<br />
===Создание виртуального каталога===
По умолчанию корневым каталогом '''IIS''' является <code>C:/Inetpub/wwwroot</code>. Для создания виртуального каталога для приложения находящегося в этом каталоге нужно выполнить следующие действия:<br />
1 Зайти в '''Пуск''' ('''Start''') &rarr; '''Настройки''' ('''Settings''') &rarr; '''Панель управления''' ('''Control Panel''') &rarr; '''Администрирование''' ('''Administrative Tools''')<br />
[[Файл: am_745.png|x500px|Панель управления]]<br />
<br />
2 '''Диспетчер служб IIS'''<br />
[[Файл: am_746.png|x500px|Администрирование - Диспетчер служб IIS]]<br />
<br />
3 В открывшемся дереве каталогов выбрать '''Web Sites – Default Web Site'''. В открывшемся списке найти ''папку'', для которой нужно создать ''виртуальный каталог'', кликнуть по ней правой кнопкой мыши и выбрать '''Преобразовать в приложение'''<br />
[[Файл: am_747.png|x500px|Преобразовать в приложение]]<br />
<br />
4 В открывшемся окне нужно нажать кнопку '''ОК'''<br />
[[Файл: am_748.png|x500px|Добавить приложение]]<br />
<br />

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

==Настройка==

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

{| border="1" cellpadding="8" style="background-color:#F9F9F9; border:#AAAAAA; border-collapse:collapse"

|- style="background-color:#F2F2F2"

! width="2%" | №
! width="28%" | Описание
! width="35%" | Значение
! width="35%" | Настройка

|- style="vertical-align:text-top"

| 1
| ISO-код рубля.<br> Настройка является обязательной!
| '''ISO-код рубля''', используемый в ПК «Мастер-Тур».
|<syntaxhighlight lang="xml" enclose="div">
<add key="RubleCurrencyISOCode" value="RUB"/>
</syntaxhighlight>

|- style="vertical-align:text-top"

| 2
| Настройка, определяющая '''дату''', на которую должен '''подбираться курс валют''' для пересчета '''суммы к оплате'''.
| 
* '''FixationDate''' или '''отсутствие настройки''' - курс на дату последней фиксации путевки на момент совершения платежа, а если путевка не зафиксирована, то на дату совершения платежа;
* '''ConfirmDate''' — курс на дату последнего ''подтверждения заявки'' (если '''подтверждения''' путевки еще '''не было''', либо '''курс''' на дату подтверждения '''не заведен''', то будет отображаться курс на '''момент совершения платежа''');
* '''OrderDate''' — дата оформления заявки; 
* '''PaymentDate''' - курс на дату совершения платежа.
|<syntaxhighlight lang="xml" enclose="div">
<add key="courseExchangeDate" value="orderdate"/>
</syntaxhighlight>
|- style="vertical-align:text-top"
| 3
| Определяет '''тип платежной операции'''.<br /><br />Тип платежной операции так же может задаваться в настройке '''SYSPaymentOperationId''' в таблице ''SystemSettings''. В таком случае в настройке '''PaymentOperationId''' задается название настройки из таблицы ''SystemSettings''.
Обязательная настройка.
| '''Идентификатор типа операции''' - поле '''PO_Id''' из таблицы <code>'''[PaymentOperations]'''</code>.<br /><br />Либо '''название настройки SYSPaymentOperationId''' из таблицы <code>'''[SystemSettings]'''</code>.
|<syntaxhighlight lang="xml" enclose="div">
<add key="PaymentOperationId" value="1" />
</syntaxhighlight>
|- style="vertical-align:text-top"
| 4
|Настройка, определяющая '''статусы путевок''', при которых '''доступна возможность оплаты''' через систему электронных платежей Alfabank (ATM).
| - '''ключи статусов''' из таблицы <code>'''[Order_Status]'''</code>, при которых ''доступна оплата'' через систему электронных платежей.
- '''отсутствие настройки''' - разрешена оплата путёвок только со статусом ''' ''Ok'' '''.
|<syntaxhighlight lang="xml" enclose="div">
<add key="paymentsStatuses" value="4,7" />
</syntaxhighlight>
|- style="vertical-align:text-top"
| 5
|Настройка, позволяющая задавать размер комиссии (в виде коэффицента), которая будет включена в сумму размера задолженности по заявке.
| Используется в методе Check
Размер задолженности умножается на коэффициент, указанный в этой настройке(целая часть отделяется либо запятой, либо точкой).
|<syntaxhighlight lang="xml" enclose="div">
<add key="ComissionCheck" value="1.03"/>
</syntaxhighlight>
|- style="vertical-align:text-top"
| 6
|Настройка, позволяющая задавать размер комиссии (в виде коэффицента), которая будет включена в сумму оплаты.
| Используется в методе Pay
Размер путевки умножается на коэффициент, указанный в этой настройке(целая часть отделяется либо запятой, либо точкой).
|<syntaxhighlight lang="xml" enclose="div">
<add key="ComissionPay" value="1.03"/>
</syntaxhighlight>
|- style="vertical-align:text-top"
| 7
|Настройка, определяющая минимальный размер комиссии в валюте путевки.
| Значение комиссии, которую необходимо включить в сумму оплаты (при проверке Check) или вычесть (при платеже Pay). 
(целая часть отделяется либо запятой, либо точкой).
|<syntaxhighlight lang="xml" enclose="div">
 <add key="MinComission" value="42"/>
</syntaxhighlight>
|- style="vertical-align:text-top"
| 8
|Настройка, определяющая минимальный размер платежа в нац. валюте, для дальнейшего расчета комиссии.
| Значение обязательно больше 0.(целая часть отделяется либо запятой, либо точкой).
Отсутствие настройки или неуказанное значение по умолчанию равно 1.<br />
Если платёж больше MinPay, то будет использован параметр ComissionCheck либо ComissionPay.<br />
Если платёж меньше MinPay, то будет использован параметр MinComission.<br />
|<syntaxhighlight lang="xml" enclose="div">
<add key="MinPay" value="2000"/>
</syntaxhighlight>
|- style="vertical-align:text-top"
| 9
|Определяет '''тип платежной системы''' при сохранении платежей.
Информация о типе платежной системы записывается в [[Мастер-Тур:Работа с группой путевок#История путевки|историю по путевке]].<br />
Для системы '''«Мастер-Финанс»''' информация записывается в столбец '''DP_PAYMENTSSYS''' таблицы <code>'''[FIN_DOGOVOR_PAID]'''</code>.<br />
Обязательная настройка.
|Название платежной системы
|<syntaxhighlight lang="xml" enclose="div">
<add key="PaymentSystem" value="AlfabankTerminals"/>
</syntaxhighlight>

|- style="vertical-align:text-top"
| 10
| Включение режима '''записи нового платежа''' в систему '''«Мастер-Финанс»'''. При этом в ПК «Мастер-Тур» платежи '''не сохраняются'''.
| 
* '''true''' - включена запись платежей в «Мастер-Финанс»;
* '''false''' или '''отсутствие настройки''' - выключает запись платежей в «Мастер-Финанс».
|<syntaxhighlight lang="xml" enclose="div">
<add key="AddPaymentsToMasterFinance" value="true" />
</syntaxhighlight> 
''В версиях до релиза 9222SP0 может использоваться старая настройка'':
<syntaxhighlight lang="xml" enclose="div">
<add key="paymentFactory" value="MasterSoft.Payments.PaymentFactoryWebPay, MasterSoft.Payments" />
</syntaxhighlight> 
|- style="vertical-align:text-top"
|}

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

==Работа в системе==
Осуществляется 2 типа запросов:
*Pay - проведение платежа,
*Check - проверка состояния счёта Плательщика.

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

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

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

*'''command'''='''check''' – запрос на проверку состояния Плательщика<br>
*'''txn_id'''=1234567 – внутренний номер платежа в системе Банка<br>
*'''account'''=DF21100001 – номер путевки в системе ПК "Мастер-Тур"<br>
*'''sum'''=0.00 – Обязательный параметр. На текущий момент не обрабатывается. Представляет собой дробное число с точностью до сотых, в качестве разделителя используется «.» (точка). 
Необязательные переменные: 
*'''txn_date'''=20230815120133 – дата учета платежа в системе Банка, которая передаётся в формате ГГГГММДДЧЧММСС. Можно не указывать. Если не указана, то по умолчанию равна дате создания путевки. Данная дата также используется для расчета курса, если путевка в валюте.<br>
Ответ клиента выглядит следующим образом:

<TABLE STYLE="border: 0.1em dashed #2F6FAB; margin: 8px; padding: 8px" WIDTH="100%"><TR><TD>
<syntaxhighlight lang="xml">
<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>
</syntaxhighlight>
</TD></TR></TABLE>

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

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

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

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

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

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

<TABLE STYLE="border: 0.1em dashed #2F6FAB; margin: 8px; padding: 8px" WIDTH="100%"><TR><TD>
<syntaxhighlight lang="xml">
<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>
</syntaxhighlight>
</TD></TR></TABLE>

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

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

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

При обработке запросов от системы Банка, сервис возвращает соответствующие коды в элементе <code><result></code>. 
{| border="1" cellpadding="8" style="background-color:#F9F9F9; border:#AAAAAA; border-collapse:collapse" width="800px"

|- style="background-color:#F2F2F2"

! width="20%" | Код
! width="50%" | Комментарий
! width="30%" | Фатальность

|- style="vertical-align:text-top"
| 0
| ОК.
| -

|- style="vertical-align:text-top"
| 1
| Временная ошибка. Повторите запрос позже.
| -

|- style="vertical-align:text-top"
| 4
| Неверный формат идентификатора Плательщика
| +

|- style="vertical-align:text-top"
| 5
| Идентификатор Плательщика не найден (Ошиблись номером)
| +

|- style="vertical-align:text-top"
| 7
| Прием платежа запрещен провайдером
| +

|- style="vertical-align:text-top"
| 8
| Прием платежа запрещен по техническим причинам
| +

|- style="vertical-align:text-top"
| 79
| Счет Плательщика не активен
| +

|- style="vertical-align:text-top"
| 79
| Счет Плательщика не активен
| +

|- style="vertical-align:text-top"
| 90
| Проведение платежа не окончено
| +

|- style="vertical-align:text-top"
| 241
| Сумма слишком мала
| +

|- style="vertical-align:text-top"
| 242
| Сумма слишком велика
| +

|- style="vertical-align:text-top"
| 243
| Невозможно проверить состояние счёта
| +

|- style="vertical-align:text-top"
| 300
| Другая ошибка провайдера
| +

|- style="vertical-align:text-top"
| 301
| Нет прав на проверку лицензии
| +

|- style="vertical-align:text-top"
| 302
| Срок лицензии истек
| +

|- style="vertical-align:text-top"
|}

[[Category:Платежные web-сервисы]]