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

Материал из Megatec
Перейти к: навигация, поиск
(→‎Установка)
(→‎Коды завершения обработки запросов)
 
(не показано 17 промежуточных версий 6 участников)
Строка 4: Строка 4:
 
<td>
 
<td>
 
Поддерживаемые версии:<br />
 
Поддерживаемые версии:<br />
−
Начиная с 2009.2.20.33<br />
+
Начиная с 2009.2.22.0<br />
 
</td>
 
</td>
 
</tr>
 
</tr>
Строка 15: Строка 15:
 
<code>mw-SberbankTerminals-9.2.20.ХХXXX.zip</code>.<br />
 
<code>mw-SberbankTerminals-9.2.20.ХХXXX.zip</code>.<br />
 
===Создание виртуального каталога===
 
===Создание виртуального каталога===
−
По умолчанию корневым каталогом '''IIS''' является <code>C:/Inetpub/wwwroot</code>. Для создания виртуального каталога для приложения находящегося в этом каталоге нужно выполнить следующие действия:<br />
+
По умолчанию корневым каталогом '''IIS''' является <code>C:/Inetpub/wwwroot</code>. Для создания виртуального каталога для приложения находящегося в этом каталоге нужно выполнить следующие действия:<br />
 
1 Зайти в '''Пуск''' ('''Start''') &rarr; '''Настройки''' ('''Settings''') &rarr; '''Панель управления''' ('''Control Panel''') &rarr; '''Администрирование''' ('''Administrative Tools''')<br />
 
1 Зайти в '''Пуск''' ('''Start''') &rarr; '''Настройки''' ('''Settings''') &rarr; '''Панель управления''' ('''Control Panel''') &rarr; '''Администрирование''' ('''Administrative Tools''')<br />
 
[[Файл: am_745.png|x500px|Панель управления]]<br />
 
[[Файл: am_745.png|x500px|Панель управления]]<br />
Строка 75: Строка 75:
 
|<syntaxhighlight lang="xml" enclose="div">
 
|<syntaxhighlight lang="xml" enclose="div">
 
<add key="PaymentOperationId" value="1" />
 
<add key="PaymentOperationId" value="1" />
 +
</syntaxhighlight>
 +
|- style="vertical-align:text-top"
 +
| 4
 +
|Настройка, определяющая '''статусы путевок''', при которых '''доступна возможность оплаты''' через систему электронных платежей Sberbank (ATM).
 +
| - '''ключи статусов''' из таблицы <code>'''[Order_Status]'''</code>, при которых ''доступна оплата'' через систему электронных платежей.
 +
- '''отсутствие настройки''' - разрешена оплата путёвок только со статусом ''' ''Ok'' '''.
 +
|<syntaxhighlight lang="xml" enclose="div">
 +
<add key="paymentsStatuses" value="4,7" />
 +
</syntaxhighlight>
 +
|- style="vertical-align:text-top"
 +
| 5
 +
|Определяет '''тип платежной системы''' при сохранении платежей.
 +
Информация о типе платежной системы записывается в [[Мастер-Тур:Работа с группой путевок#История путевки|историю по путевке]].<br />
 +
Для системы '''«Мастер-Финанс»''' информация записывается в столбец '''DP_PAYMENTSSYS''' таблицы <code>'''[FIN_DOGOVOR_PAID]'''</code>.<br />
 +
Обязательная настройка.
 +
|Название платежной системы
 +
|<syntaxhighlight lang="xml" enclose="div">
 +
<add key="PaymentSystem" value="SberbankTerminals"/>
 
</syntaxhighlight>
 
</syntaxhighlight>
  
 +
|- style="vertical-align:text-top"
 +
| 6
 +
| Включение режима '''записи нового платежа''' в систему '''«Мастер-Финанс»'''. При этом в ПК «Мастер-Тур» платежи '''не сохраняются'''.
 +
|
 +
* '''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"
 +
 +
| 7
 +
| Настройка, позволяющая задавать '''размер комиссии''', которая будет '''включена в сумму оплаты'''.
 +
| '''Значение комиссии''', которую необходимо ''включить в сумму платежа'' (целая часть отделяется либо запятой, либо точкой).<br />
 +
Комиссия указывается '''в процентах'''. По умолчанию комиссия равна нулю.
 +
|<syntaxhighlight lang="xml" enclose="div">
 +
<add key="Commission" value="2.5" />
 +
</syntaxhighlight>
 
|- style="vertical-align:text-top"
 
|- style="vertical-align:text-top"
 
|}
 
|}
Строка 106: Строка 146:
 
<syntaxhighlight lang="xml">
 
<syntaxhighlight lang="xml">
 
<response xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 
<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>
+
     <osmp_txn_id>1234567</osmp_txn_id>
 
     <result>0</result>
 
     <result>0</result>
 
     <comment/>
 
     <comment/>
 
     <sum>148139.25</sum>
 
     <sum>148139.25</sum>
−
     <inn/>
+
     <inn>7701100000</inn>
 
     <rs>111111111111111100000000000000</rs>
 
     <rs>111111111111111100000000000000</rs>
 
     <bik>044525593</bik>
 
     <bik>044525593</bik>
Строка 116: Строка 156:
 
     <name>Фирма-владелец</name>
 
     <name>Фирма-владелец</name>
 
     <bank_name>Тестовый банк</bank_name>
 
     <bank_name>Тестовый банк</bank_name>
 +
    <info>Дата начала тура: 17.04.2017</info>
 +
    <fio>EGOROV I.</fio>
 
</response>
 
</response>
 
</syntaxhighlight>
 
</syntaxhighlight>
Строка 121: Строка 163:
  
 
Возвращаемые значения:
 
Возвращаемые значения:
−
*'''<osmp_txn_id>''' - номер транзакции в системе Банка, который передается Клиенту в переменной txn_id
+
*'''<osmp_txn_id>''' - Номер транзакции в системе Банка, который передается Клиенту в переменной <code>txn_id</code>.
−
*'''<result>''' - код результата завершения запроса
+
*'''<result>''' - Код результата завершения запроса.
−
*'''<comment>''' - необязательный элемент – комментарий завершения операции
+
*'''<comment>''' - Необязательный элемент – комментарий завершения операции.
−
*'''<sum>''' - сумма платежа. Представляет собой дробное число с точностью до сотых, в качестве разделителя используется «.» (точка).
+
*'''<sum>''' - Сумма платежа. Представляет собой дробное число с точностью до сотых, в качестве разделителя используется «.» (точка).
 
*'''<inn>''' - ИНН Плательщика.
 
*'''<inn>''' - ИНН Плательщика.
−
*'''<rs>''' - расчётный счёт Плательщика.
+
*'''<rs>''' - Расчётный счёт Плательщика.
 
*'''<bik>''' - БИК Банка Плательщика.
 
*'''<bik>''' - БИК Банка Плательщика.
−
*'''<ks>''' - кор. счёт Банка Плательщика
+
*'''<ks>''' - Кор. счёт Банка Плательщика.
−
*'''<name>''' - наименование Плательщика.
+
*'''<name>''' - Наименование Плательщика.
−
*'''<bank_name>''' - наименование банка Плательщика.
+
*'''<bank_name>''' - Наименование банка Плательщика.
 +
*'''<info>''' - Дополнительная информация.
 +
*'''<fio>''' - Фамилия, имя главного туриста по путёвке.
 +
 
 +
Возврат <code><result>0</result></code> на запрос «check» свидетельствует о том, что лицевой счет Плательщика с соответствующим ему номером <code>osmp_txn_id</code> может быть пополнен на сумму, указанную в запросе.<br /><br />
  
−
Возврат <code><result>0</result></code> на запрос «check» свидетельствует о том, что лицевой счет Плательщика с соответствующим ему номером <code>osmp_txn_id</code> может быть пополнен на сумму, указанную в запросе.
+
Если приходит запрос с тем же '''txn_id''', то осуществляется проверка, записали ли мы этот номер в историю и совпадает ли по нему вновь пришедшая сумма и та сумма оплаты, которая прошла с этим номером ранее.
 +
* если '''txn_id''' уже есть в базе и суммы совпадают, то возвращается код <code><result>0</result></code> и сообщение, что транзакция уже была добавлена ранее
 +
* если '''txn_id''' нет в базе, то создается платеж на вновь пришедшую сумму, возвращается код <code><result>0</result></code> и сообщение, что оплата прошла успешно
 +
* если '''txn_id''' уже есть в базе, на суммы не совпадают, возвращается код <code><result>8</result></code> и сообщение, что транзакция уже была добавлена ранее и что суммы не совпадают
  
 
===Запрос на пополнение лицевого счёта плательщика===
 
===Запрос на пополнение лицевого счёта плательщика===
Строка 243: Строка 292:
 
| 300
 
| 300
 
| Другая ошибка провайдера
 
| Другая ошибка провайдера
 +
| +
 +
 +
|- style="vertical-align:text-top"
 +
| 301
 +
| Нет прав на проверку лицензии
 +
| +
 +
 +
|- style="vertical-align:text-top"
 +
| 302
 +
| Срок лицензии истек
 +
| +
 +
 +
|- style="vertical-align:text-top"
 +
| 303
 +
| Оплата путевки невозможна, обратитесь к туроператору
 
| +
 
| +
  

Текущая версия на 15:33, 29 апреля 2022

Версия статьи от 29-04-2022.

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


Введение

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

Установка

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

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

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

2 Диспетчер служб IIS
Администрирование - Диспетчер служб IIS

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

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

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

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

Настройка

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

№ Описание Значение Настройка
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 Настройка, определяющая статусы путевок, при которых доступна возможность оплаты через систему электронных платежей Sberbank (ATM). - ключи статусов из таблицы [Order_Status], при которых доступна оплата через систему электронных платежей.

- отсутствие настройки - разрешена оплата путёвок только со статусом Ok . 

<add key="paymentsStatuses" value="4,7" />
5 Определяет тип платежной системы при сохранении платежей.

Информация о типе платежной системы записывается в историю по путевке.
Для системы «Мастер-Финанс» информация записывается в столбец DP_PAYMENTSSYS таблицы [FIN_DOGOVOR_PAID].
Обязательная настройка.

Название платежной системы 
<add key="PaymentSystem" value="SberbankTerminals"/>
6 Включение режима записи нового платежа в систему «Мастер-Финанс». При этом в ПК «Мастер-Тур» платежи не сохраняются.
  • true - включена запись платежей в «Мастер-Финанс»;
  • false или отсутствие настройки - выключает запись платежей в «Мастер-Финанс».
 
<add key="AddPaymentsToMasterFinance" value="true" />

В версиях до релиза 9222SP0 может использоваться старая настройка: 

<add key="paymentFactory" value="MasterSoft.Payments.PaymentFactoryWebPay, MasterSoft.Payments" />
7 Настройка, позволяющая задавать размер комиссии, которая будет включена в сумму оплаты. Значение комиссии, которую необходимо включить в сумму платежа (целая часть отделяется либо запятой, либо точкой).

Комиссия указывается в процентах. По умолчанию комиссия равна нулю. 

<add key="Commission" value="2.5" />

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

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

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

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

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

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

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

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

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

  • command=check – запрос на проверку состояния Плательщика
  • txn_date=20160815120133 – дата учета платежа в системе Банка, которая передаётся в формате ГГГГММДДЧЧММСС.
  • txn_id=1234567 – внутренний номер платежа в системе Банка
  • 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/>
    <sum>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> - Необязательный элемент – комментарий завершения операции.
  • <sum> - Сумма платежа. Представляет собой дробное число с точностью до сотых, в качестве разделителя используется «.» (точка).
  • <inn> - ИНН Плательщика.
  • <rs> - Расчётный счёт Плательщика.
  • <bik> - БИК Банка Плательщика.
  • <ks> - Кор. счёт Банка Плательщика.
  • <name> - Наименование Плательщика.
  • <bank_name> - Наименование банка Плательщика.
  • <info> - Дополнительная информация.
  • <fio> - Фамилия, имя главного туриста по путёвке.

Возврат <result>0</result> на запрос «check» свидетельствует о том, что лицевой счет Плательщика с соответствующим ему номером osmp_txn_id может быть пополнен на сумму, указанную в запросе.

Если приходит запрос с тем же txn_id, то осуществляется проверка, записали ли мы этот номер в историю и совпадает ли по нему вновь пришедшая сумма и та сумма оплаты, которая прошла с этим номером ранее.

  • если txn_id уже есть в базе и суммы совпадают, то возвращается код <result>0</result> и сообщение, что транзакция уже была добавлена ранее
  • если txn_id нет в базе, то создается платеж на вновь пришедшую сумму, возвращается код <result>0</result> и сообщение, что оплата прошла успешно
  • если txn_id уже есть в базе, на суммы не совпадают, возвращается код <result>8</result> и сообщение, что транзакция уже была добавлена ранее и что суммы не совпадают

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

https://localhost/SberbankTerminals/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/>
    <sum>10.45</sum>
    <prv_txn>56</prv_txn>
</response>

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

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

Возвращая <result>0</result> на запрос «pay», Клиент сообщает об успешном завершении операции пополнения баланса. Система полностью завершает обработку данной транзакции.

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

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

Код Комментарий Фатальность
0 ОК. -
1 Временная ошибка. Повторите запрос позже. -
4 Неверный формат идентификатора Плательщика +
5 Идентификатор Плательщика не найден (Ошиблись номером) +
7 Прием платежа запрещен провайдером +
8 Прием платежа запрещен по техническим причинам +
79 Счет Плательщика не активен +
79 Счет Плательщика не активен +
90 Проведение платежа не окончено +
241 Сумма слишком мала +
242 Сумма слишком велика +
243 Невозможно проверить состояние счёта +
300 Другая ошибка провайдера +
301 Нет прав на проверку лицензии +
302 Срок лицензии истек +
303 Оплата путевки невозможна, обратитесь к туроператору +
Источник — «http://wiki.megatec.ru/index.php?title=Платежные_web-сервисы:_Сервис_интеграции_с_платежной_системой_Sberbank_ATM_(оплата_через_терминалы,_кассы_банка,_Сбербанк_Онлайн)&oldid=27427»