Платежные web-сервисы: Сервис интеграции с платежной системой Tinkoff (Т-Банк) (оплата картой в личном кабинете)

Версия статьи от 12-01-2024

Начиная с релиза 15.8 после 01.06.2023 работа с отдельными платежными шлюзами не поддерживается. Для работы необходимо использовать новую версию приложения EntryPoint (оплата картой в личном кабинете с выбором системы оплаты) с поддержкой Uniteller, Sberbank, Tinkoff, Alfabank, Assist, PayOnline, WebPay без установки сторонних библиотек и развертывания отдельных сервисов.

Введение

Перед началом работы с платежными системами необходимо удостовериться в соответствии оборудования и программного обеспечения системно-аппаратным требованиям. Если версия операционной системы не соответствует рекомендуемой, то работа с платежными сервисами не гарантирована в связи с ограничениями протоколов безопасности операционной системы.

Данный модуль реализует возможность оплаты путевок через систему электронных платежей «Tinkoff».
Широкое распространение «Tinkoff» позволяет предоставить возможность онлайн оплаты большому количеству пользователей. Особенно полезным данный модуль может быть туристическим компаниям, ориентированным на работу с частными клиентами.

Установка

Для установки дополнительного модуля Сервис интеграции с платежной системой «Tinkoff» нужно создать директорию Tinkoff в каталоге C:/inetpub/wwwroot (корневом каталоге IIS) и выложить туда распакованные файлы из архива
payments-tinkoff-X.X.XX.XXXXX.zip.
Устанавливать дополнительный модуль необходимо в том же домене, где расположено основное приложение ПК «Мастер-Web».
Начиная с релиза 15.5, если используется дополнительный модуль Выбор платежной системы (оплата картой в личном кабинете), то необходимо скопировать файл Megatec.MasterWeb.PaymentSystem.Tinkoff.dll из /Tinkoff/bin/ и разместить в папке /EntryPoint/bin/.
В управлении IIS необходимо создать виртуальный каталог для папки Tinkoff.

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

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


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


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


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

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

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

Настройка

После установки надстройка Сервис интеграции с платежной системой Tinkoff доступна в экранах «Список заявок» и «Информация о заказе».

Настройки ПК «Мастер-Web»

Настройки задаются в секции <appSettings> файла web.config основного приложения ПК «Мастер-Web».

№	Описание	Значение	Настройка
1	Включение дополнительного модуля Система онлайн платежей. Обязательная настройка. Внимание! Путь к приложению обязательно должен содержать ссылку на приложение из внешней сети. В противном случае, она не будет работать.	Путь к приложению «Система онлайн платежей».	<add key="paymentsLink" value="http://somesite/Tinkoff" />
2	Настройка, определяющая статусы путевок, при которых доступна возможность оплаты через систему электронных платежей «Tinkoff». Обязательная настройка.	Ключи статусов из таблицы [Order_Status], при которых доступна оплата через «Tinkoff».	<add key="paymentsStatuses" value="7,37" />
3	Настройка, позволяющая выводить предупреждающее сообщение о снятии комиссии при оплате.	true — сообщение отображается; false или отсутствие настройки — сообщение не отображается.	<add key="askUserBeforePayment" value="true" />
4	Настройка, включающая механизм хэширования пароля пользователя, сохраняемого в файлах cookie, что позволяет усилить безопасность ПК «Мастер-Web». По умолчанию хэширование включено. Важно! Если данная настройка прописана в файле web.config основного приложения, то она должна быть прописана и в платежном сервисе с тем же значением.	false или отсутствие настройки - хэширование пароля в файлах cookie выключено; true - хэширование пароля в файлах cookie включено.	<add key="HashPasswordForCookie" value="true" />
5	Настройка, определяющая партнеров в базе ПК «Мастер-Тур», которым разрешено осуществлять оплату путёвок онлайн.	Ключи партнеров таблицы [tbl_Partners], которым разрешена онлайн-оплата путёвок; пустое значение или отсутствие настройки – онлайн-оплата путёвок доступна всем партнёрам.	<add key="allowedPaymentPartnerKeys" value="10764"/>
6	Настройка, позволяющая производить оплату в новой вкладке браузера. Внимание! Настройка обрабатывается, начиная с релиза 9222SP0. Важно! Если данная настройка прописана в файле web.config основного приложения, то она должна быть прописана и в платежном сервисе с тем же значением.	false или отсутствие настройки - оплата производится в текущей вкладке браузера; true - оплата производится в новой вкладке браузера.	<add key="OpenPaymentInNewWindow" value="true" />

Настройки приложения «Система онлайн платежей»

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

№	Описание	Значение	Настройка
1	Адрес платежной службы Обязательная настройка.	Адрес сервиса оплаты через карту банка «Tinkoff».	<add key="LoginUrl" value="https://securepay.tinkoff.ru/v2/Init"/>
1	Адрес платежной службы Обязательная настройка.	Адрес сервиса оплаты через карту банка «Tinkoff».	<add key="LoginUrl" value="https://securepay.tinkoff.ru/v2/Init"/>
2	Адрес для оплаты по QR коду Обязательная настройка.	Адрес сервиса оплаты через карту банка «Tinkoff» по QR коду.	<add key="QRCodeUrl" value="https://securepay.tinkoff.ru/v2/GetQr"/>
3	Адрес метода для получения статуса платежа Обязательная настройка.	Адрес метода для получения статуса платежа.	<add key="GetStateUrl" value="https://securepay.tinkoff.ru/v2/GetState"/>
4	Адрес метода возвращающего статус заказа Обязательная настройка.	Адрес метода возвращающего статус заказа.	<add key="CheckOrderUrl" value="https://securepay.tinkoff.ru/v2/CheckOrder"/>
5	Идентификатор терминала Обязательная настройка.	Параметр Терминал из раздела Терминалы в л/к сервиса «Tinkoff».	<add key="TerminalKey" value="1587990738"/>
6	Пароль терминала Обязательная настройка.	Параметр Пароль из раздела Терминалы в л/к сервиса «Tinkoff».	<add key="TerminalPassword" value="cn5du3jxcfbmwtyuii"/>
7	Настройка, определяющая язык окна платежной формы «Tinkoff». Обязательная настройка.	ru - русский язык en - английский язык	<add key="LanguageFormCode" value="ru"/>
8	Код системы налогообложения, его значение должно соответствовать режимам налогообложения, сконфигурированным в ККМ при регистрации. Данная настройка необходима для работы фискализации платежей.	osn – общая система налогообложения usn_income – упрощенная система налогообложения (Доход) usn_income_outcome – упрощенная СН (Доход минус Расход) patent – патентная система налогообложения envd – единый налог на вмененный доход esn – единый сельскохозяйственный налог	<add key="TaxationCode" value="osn"/>
9	Код ставки налогообложения. Данная настройка необходима для работы фискализации платежей.	none – не облагается НДС vat0 – облагается НДС по ставке 0% vat10 – облагается НДС по ставке 10% vat20 – облагается НДС по ставке 20% vat110 – облагается НДС по ставке 10/110 vat120 – облагается НДС по ставке 18/120	<add key="Tax" value="none"/>
10	Настройка, определяющая тип операции при проведении платежа. Обязательная настройка.	Ключ операции (Поле PO_ID из таблицы [PaymentOperations]).	<add key="PaymentOperationId" value="6" />
11	Настройка, определяющая тип операции при проведении платежа для комиссий.	Ключ операции (Поле PO_ID из таблицы [PaymentOperations]).	<add key="paymentOperationCommissionId" value="" />
12	Настройка, определяющая пользователя ПК «Мастер-Тур», к которому будет привязываться оплата. Обязательная настройка.	Ключ пользователя, к которому привязывается оплата (Поле US_KEY из таблицы [UserList]).	<add key="masterTourUser" value="80" />
13	Настройка, определяющая партнера, к которому будет привязываться оплата. Обязательная настройка.	Ключ филиала, к которому привязывается оплата (Поле PR_KEY из таблицы [Partners]).	<add key="paymentFilialKey" value="1" />
14	Настройка, определяющая отдел, к которому будет привязываться оплата. Обязательная настройка.	Ключ отдела (кассы), к которому привязывается оплата (Поле PDP_KEY из таблицы [PrtDeps]).	<add key="departmentKey" value="2" />
15	Настройка, позволяющая задавать размер комиссии, которая будет включена в сумму оплаты (для агентств)	Значение комиссии, которую необходимо включить в сумму платежа (целая часть отделяется запятой). Комиссия указывается в процентах.	<add key="addAgencyComission" value="15,8" />
16	Настройка, позволяющая задавать размер комиссии, которая будет включена в сумму оплаты (для частных лиц)	Значение комиссии, которую необходимо включить в сумму платежа (целая часть отделяется запятой). Комиссия указывается в процентах.	<add key="addPersonalComission" value="17,4" />
17	Настройка, задающая услугу, которая добавится в путевку при наличии комиссии, и стоимость которой будет равна сумме комиссии. Работает вместе с настройками NewDogovorServiceSvKey и NewDogovorServicePartnerKey. Обрабатывается с релиза 15.8.	Ключ услуги (Поле SL_KEY из таблицы [ServiceList]).	<add key="NewDogovorServiceServiceListKey" value="450" />
18	Настройка, задающая класс для услуги, добавляемой в путевку при наличии комиссии. Работает вместе с настройками NewDogovorServiceServiceListKey и NewDogovorServicePartnerKey. Обрабатывается с релиза 15.8.	Ключ класса услуги (Поле SV_KEY из таблицы [Service]).	<add key="NewDogovorServiceSvKey" value="1055" />
19	Настройка, задающая партнера, которая будет являться поставщиком для услуги, добавляемой в путевку при наличии комиссии. Работает вместе с настройками NewDogovorServiceServiceListKey и NewDogovorServiceSvKey. Обрабатывается с релиза 15.8.	Ключ класса услуги (Поле PR_KEY из таблицы [Partners]).	<add key="NewDogovorServicePartnerKey" value="12921" />

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

№	Описание	Значение	Настройка
1	Имя текущей установленной службы.	Наименование службы, к которой может обращаться текущий клиент (по значению настройки acceptableServices в MasterTourService). По умолчанию настройка не заполнена. Значение настройки должно быть явно задано.	<add key="acceptableServices" value=""/>
2	Включение режима записи нового платежа в систему «Мастер-Финанс». При этом в ПК «Мастер-Тур» платежи не сохраняются.	true - включена запись платежей в «Мастер-Финанс»; false или отсутствие настройки - выключает запись платежей в «Мастер-Финанс».	<add key="AddPaymentsToMasterFinance" value="true" />
3	Настройка, определяющая дату, на которую будет подбираться курс валют для пересчета суммы к оплате.	FixationDate или отсутствие настройки - курс на дату последней фиксации путевки на момент совершения платежа, а если путевка не зафиксирована, то на дату совершения платежа; ConfirmDate — курс на дату последнего подтверждения заявки (если подтверждения путевки еще не было, либо курс на дату подтверждения не заведен, то будет отображаться курс на момент совершения платежа); OrderDate — дата оформления заявки; PaymentDate - курс на дату совершения платежа.	<add key="courseExchangeDate" value="FixationDate" />

Начиная с релиза 15.8 появилась возможность добавления услуги комиссии от оплаты через платежный шлюз в путевку и формирования ПКО различным образом.

Сценарии работы

Предполагаются 3 сценария работы:
1. Заданы размеры комиссий и параметры paymentOperationId, paymentOperationComissionId, NewDogovorServiceSvKey, NewDogovorServiceServiceListKey, NewDogovorServicePartnerKey. В этом случае при оплате в базе данных формируется 1 ПКО (сумма за путевку + сумма комиссии), в путевке создается услуга "Комиссия при оплате через платежный шлюз" и сумма путевки увеличивается на размер стоимости созданной услуги.
2. Заданы размеры комиссий и параметры paymentOperationId, paymentOperationComissionId. Параметры NewDogovorServiceSvKey, NewDogovorServiceServiceListKey, NewDogovorServicePartnerKey не заданы. В этом случае при оплате в базе данных формируются 2 ПКО (отдельно за путевку и за комиссию). Услуга в путевке не создается и сумма путевки не меняется.
3. Заданы размеры комиссий и параметр paymentOperationId. Значение параметра paymentOperationComissionId=0 или параметр отсутствует. Оплата за комиссию уходит сразу в банк. В этом случае при оплате в базе данных формируется 1 ПКО за путевку.
Внимание! Данные настройки не работают при включенной настройке <add key="AddPaymentsToMasterFinance" value="true"/>.

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

Оплату можно произвести по путевкам, статус которых указан в настройке paymentsStatuses.
В разделе Терминалы л/к «Tinkoff» в настройке Ссылка для уведомлений необходимо указать URL-адрес уведомления магазина в формате: somesite/Tinkoff/Payment.aspx?action=reply.

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

Поиск путевки

Список заявок, забронированных в базе данных туроператора, доступен в экране «Список заказов» по адресу: http://ip-адрес сервера Мастер-Веб/MasterWebStandard/OrderList.aspx.

Экран «Список заказов» доступен только для зарегистрированных и авторизованных в системе пользователей.

После ввода имени пользователя и пароля загрузится список заявок, оформленных на покупателя/агентство, указанного в поле «Партнер в БД МТ» при регистрации пользователя в Системе администрирования ПК «Мастер-Web», который сопоставлен имени текущего пользователя.

Для отбора путевок можно использовать фильтры:

• Поиск по номеру заявки;
• Поиск по фамилии туриста;
• Поиск по статусу документов на визу;
• Поиск по стране;
• Поиск по дате заявки;
• Дата тура с... и Дата тура по...;
• Путевки с наличием услуги «Виза»;
• Путевки с задолженностями.

Оплата путевки

Оплата доступна только для путевок имеющих статус, ключ которого указан в настройке paymentsStatuses.

Оплата путевок доступна в экранах «Список заявок» и «Информация о заказе».

Экран Список заказов доступен по адресу: http://ip-адрес сервера Мастер-Веб/MasterWebStandard/OrderList.aspx.

Экран Информация о заказе доступен по адресу: http://ip-адрес сервера Мастер-Веб/MasterWebStandard/OrderInfo.aspx.

Для оплаты путевки через систему электронных платежей «Tinkoff» необходимо нажать ссылку Оплатить для нужной путевки или кнопку Оплатить on-line в экране Информация о заказе.

Для оплаты путевки необходимо ввести данные банковской карты, с помощью которой производится оплата:

После того, как все поля заполнены, нужно нажать на кнопку Оплатить.

При успешном проведении платежа в базе автоматически создается проводка и у путевки прописывается сумма оплаты. На указанную электронную почту приходят квитанции об оплате, в л/к «Tinkoff» в разделе Операции со статусом Подтвержден появляются данные о проведенном платеже, включая номер путевки. Также в истории путевки добавляется запись об оплате через платежную систему «Tinkoff».

Оплата путевки по QR коду

Оплата доступна только после включения в личном кабинете «Tinkoff» приема оплат по QR коду.
На текущий момент оплата доступна если используется дополнительный модуль Выбор платежной системы (оплата картой в личном кабинете).
Частичная оплата при оплате по QR-коду не предусмотрена в связи с ограничением системы быстрых платежей.

Для оплаты путевки через систему электронных платежей «Tinkoff» необходимо нажать ссылку Оплатить для нужной путевки или кнопку Оплатить on-line в экране Информация о заказе.
Произойдет переход к выбору платежных систем в котором необходимо выбрать кнопку с логотипом «Tinkoff» и подписью «Оплата по QR».


После выбора произойдет переход на страницу с QR кодом, который необходимо отсканировать платежным приложением банка и оплатить.

После оплаты по QR коду переход на страницу, с которой совершалась оплата, невозможен в связи с функционалом работы Системы Быстрых Платежей.

Ошибка SecureChannelFailure

Появление такой ошибки может быть вызвано невозможностью установить TLS соединение, которое используется для передачи данных от платежной системы. Вызвано некорректными настройками брандмауэра/firewall или некорректными настройками сервера. В случае обнаружения закрытого канала TLS необходимо обратиться к администратору вашей интернет-сети.

On error occurred during signing in. Contact our manager System.Exception: Some error occured: SecureChannelFailure at Megatec.MasterWeb.PaymentSystem.Tinkoff.TinkoffGateway.Authorization(TinkoffParameters parameters, String token) in C:\Users\vmizh\Work\MasterTour\Source\MW\Megatec.MasterWeb.PaymentSystem.Tinkoff\TinkoffGateway.cs:line 430 at Megatec.MasterWeb.PaymentSystem.Tinkoff.TinkoffGateway.Login(IPaymentParameters parameters) in C:\Users\vmizh\Work\MasterTour\Source\MW\Megatec.MasterWeb.PaymentSystem.Tinkoff\TinkoffGateway.cs:line 106 at MasterWebStandard2.Payment.ParseRequest(String action, String orderCode)

Для проверки доступности TLS соединения необходимо выполнить следующую команду в командной строке или в оболочке Powershell, заменив ссылку на ссылку для необходимой системы оплаты:
Invoke-WebRequest -Uri https://securepay.tinkoff.ru

Вариант успешного ответа при доступном соединении

Invoke-WebRequest : Удаленный сервер возвратил ошибку: (404) Не найден.
строка:1 знак:1
+ Invoke-WebRequest -Uri https://securepay.tinkoff.ru

Вариант некорректного ответа при закрытом соединении

Invoke-WebRequest : The request was aborted: Could not create SSL/TLS secure channel.
At line:1 char:2
+  Invoke-WebRequest -Uri https://securepay.tinkoff.ru