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

Материал из Megatec
Версия от 15:33, 29 апреля 2022; Aefremov (обсуждение | вклад) (Коды завершения обработки запросов)
(разн.) ← Предыдущая | Текущая версия (разн.) | Следующая → (разн.)
Перейти к: навигация, поиск

Версия статьи от 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 Оплата путевки невозможна, обратитесь к туроператору +