Платежные web-сервисы: Сервис интеграции с платежной системой Sberbank ATM (оплата через терминалы, кассы банка, Сбербанк Онлайн) — различия между версиями
Aefremov (обсуждение | вклад) (→Коды завершения обработки запросов) |
|||
| (не показаны 23 промежуточные версии 6 участников) | |||
| Строка 4: | Строка 4: | ||
<td> | <td> | ||
Поддерживаемые версии:<br /> | Поддерживаемые версии:<br /> | ||
| − | Начиная с 2009.2. | + | Начиная с 2009.2.22.0<br /> |
</td> | </td> | ||
</tr> | </tr> | ||
| Строка 12: | Строка 12: | ||
Данный модуль реализует возможность оплаты путёвок в ПК «Мастер-Web» через терминалы, банкоматы, кассы '''Сбербанка'''.<br> Широкое распространение Сбербанка позволяет предоставить возможность оплаты большому количеству пользователей. Особенно полезным данный модуль может быть туристическим компаниям, ориентированным на работу с частными клиентами.<br /> | Данный модуль реализует возможность оплаты путёвок в ПК «Мастер-Web» через терминалы, банкоматы, кассы '''Сбербанка'''.<br> Широкое распространение Сбербанка позволяет предоставить возможность оплаты большому количеству пользователей. Особенно полезным данный модуль может быть туристическим компаниям, ориентированным на работу с частными клиентами.<br /> | ||
==Установка== | ==Установка== | ||
| − | Для установки дополнительного модуля '''Сервис интеграции с платежной системой Sberbank | + | Для установки дополнительного модуля '''Сервис интеграции с платежной системой Sberbank (АТМ)''' нужно создать директорию '''SberbankTerminals''' в каталоге <code>C:/inetpub/wwwroot</code> (корневом каталоге '''IIS''') и выложить туда распакованные файлы из архива<br /> |
<code>mw-SberbankTerminals-9.2.20.ХХXXX.zip</code>.<br /> | <code>mw-SberbankTerminals-9.2.20.ХХXXX.zip</code>.<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" | ||
|} | |} | ||
| Строка 91: | Строка 131: | ||
Для проверки состояния Плательщика, система Банка генерирует запрос следующего вида: | Для проверки состояния Плательщика, система Банка генерирует запрос следующего вида: | ||
| − | <code>https://localhost/SberbankTerminals/api/Pay?command=check&txn_id=1234567&account= | + | <code>https://localhost/SberbankTerminals/api/Pay?command=check&txn_date=20160815120133&txn_id=1234567&account=DF21100001&sum=10.45</code> |
Строка запроса содержит следующие обязательные переменные: | Строка запроса содержит следующие обязательные переменные: | ||
*'''command'''='''check''' – запрос на проверку состояния Плательщика<br> | *'''command'''='''check''' – запрос на проверку состояния Плательщика<br> | ||
| + | *'''txn_date'''=20160815120133 – дата учета платежа в системе Банка, которая передаётся в формате ГГГГММДДЧЧММСС.<br> | ||
*'''txn_id'''=1234567 – внутренний номер платежа в системе Банка<br> | *'''txn_id'''=1234567 – внутренний номер платежа в системе Банка<br> | ||
| − | *'''account'''= | + | *'''account'''=DF21100001 – идентификатор Плательщика в информационной системе Клиента<br> |
| − | *'''sum'''=10.45 – сумма к зачислению на лицевой счет Плательщика.Представляет собой дробное число с точностью до сотых, в качестве разделителя используется «.» (точка). | + | *'''sum'''=10.45 – сумма к зачислению на лицевой счет Плательщика. Представляет собой дробное число с точностью до сотых, в качестве разделителя используется «.» (точка). |
Ответ клиента выглядит следующим образом: | Ответ клиента выглядит следующим образом: | ||
| Строка 105: | Строка 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> | |
<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> | ||
| Строка 115: | Строка 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> | ||
| Строка 120: | Строка 163: | ||
Возвращаемые значения: | Возвращаемые значения: | ||
| − | *'''<osmp_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 /> | ||
| − | + | Если приходит запрос с тем же '''txn_id''', то осуществляется проверка, записали ли мы этот номер в историю и совпадает ли по нему вновь пришедшая сумма и та сумма оплаты, которая прошла с этим номером ранее. | |
| + | * если '''txn_id''' уже есть в базе и суммы совпадают, то возвращается код <code><result>0</result></code> и сообщение, что транзакция уже была добавлена ранее | ||
| + | * если '''txn_id''' нет в базе, то создается платеж на вновь пришедшую сумму, возвращается код <code><result>0</result></code> и сообщение, что оплата прошла успешно | ||
| + | * если '''txn_id''' уже есть в базе, на суммы не совпадают, возвращается код <code><result>8</result></code> и сообщение, что транзакция уже была добавлена ранее и что суммы не совпадают | ||
===Запрос на пополнение лицевого счёта плательщика=== | ===Запрос на пополнение лицевого счёта плательщика=== | ||
| − | <code>https://localhost/SberbankTerminals/api/Pay?command=pay&txn_id=1234567&txn_date= | + | <code>https://localhost/SberbankTerminals/api/Pay?command=pay&txn_id=1234567&txn_date=20160815120133&account=DF21100001&sum=10.45</code> |
Строка запроса содержит следующие обязательные переменные: | Строка запроса содержит следующие обязательные переменные: | ||
| Строка 141: | Строка 191: | ||
*'''command'''='''pay''' – запрос на пополнение баланса Плательщика<br> | *'''command'''='''pay''' – запрос на пополнение баланса Плательщика<br> | ||
*'''txn_id'''=1234567 – внутренний номер платежа в системе Банка<br> | *'''txn_id'''=1234567 – внутренний номер платежа в системе Банка<br> | ||
| − | *'''txn_date'''= | + | *'''txn_date'''=20160815120133 – дата учета платежа в системе Банка, которая передаётся в формате ГГГГММДДЧЧММСС.<br> |
| − | *'''account'''= | + | *'''account'''=DF21100001 – идентификатор Плательщика в информационной системе Клиента.<br> |
| − | *'''sum'''=10.45 – сумма к зачислению на лицевой счет Плательщика<br> | + | *'''sum'''=10.45 – сумма к зачислению на лицевой счет Плательщика. Представляет собой дробное число с точностью до сотых, в качестве разделителя используется «.» (точка). <br> |
Ответ клиента выглядит следующим образом: | Ответ клиента выглядит следующим образом: | ||
| Строка 242: | Строка 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.
|
Поддерживаемые версии: |
Содержание
Введение
Данный модуль реализует возможность оплаты путёвок в ПК «Мастер-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
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 | Настройка, определяющая дату, на которую должен подбираться курс валют для пересчета суммы к оплате. |
|
<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 | Определяет тип платежной системы при сохранении платежей.
Информация о типе платежной системы записывается в историю по путевке. |
Название платежной системы | <add key="PaymentSystem" value="SberbankTerminals"/>
|
| 6 | Включение режима записи нового платежа в систему «Мастер-Финанс». При этом в ПК «Мастер-Тур» платежи не сохраняются. |
|
<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 - проверка состояния счёта Плательщика.
Запрос на проверку состояния счёта плательщика
Для проверки состояния Плательщика, система Банка генерирует запрос следующего вида:
Строка запроса содержит следующие обязательные переменные:
- 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>и сообщение, что транзакция уже была добавлена ранее и что суммы не совпадают
Запрос на пополнение лицевого счёта плательщика
Строка запроса содержит следующие обязательные переменные:
- 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 | Оплата путевки невозможна, обратитесь к туроператору | + |
