Платежные web-сервисы: Сервис интеграции с платежной системой (оплата через терминалы)
Версия статьи от 24-12-2015. Для перехода на версию статьи, соответствующую используемой Вами версии программы, нажмите ссылку в таблице ниже:
Более ранние версии: |
Содержание
- 1 Введение
- 2 Установка
- 3 Настройка
- 4 Подготовка данных
- 5 Логирование
- 6 Работа в системе
Введение
Данный модуль предназначен для проверки заявки и проведения платежа через платежную систему в базу туроператора. Модуль совместим со следующими платежными системами:
Ссылка на тестовый сервис
С работой тестового сервиса интеграции с платежной системой вы можете ознакомиться на нашем демо-сервере.
Установка
Для установки Сервис интеграции с платежной системой нужно создать директорию Finance в каталоге c:/inetpub/wwwroot/
(корневом каталоге IIS) и выложить туда распакованные файлы из архива mw-finance-2007.2.XX.XXXX.zip
В управлении IIS необходимо создать виртуальный каталог для папки Finance.
Создание виртуального каталога
По умолчанию корневым каталогом IIS является C:/Inetpub/wwwroot
. Для создания виртуального каталога для приложения находящегося в этом каталоге нужно выполнить следующие действия:
1 Зайти в Пуск (Start) → Настройки (Settings) → Панель управления (Control Panel) → Администрирование (Administrative Tools)
2 Диспетчер служб IIS
3 В открывшемся дереве каталогов выбрать Web Sites – Default Web Site. В открывшемся списке найти папку, для которой нужно создать виртуальный каталог, кликнуть по ней правой кнопкой мыши и выбрать Преобразовать в приложение
4 В открывшемся окне нужно нажать кнопку ОК
Подключение к базе данных ПК «Мастер-Тур»
В файле web.config
, расположенном в папке Finance пропишите необходимые параметры подключения (красным цветом выделены значения, которые необходимо ввести).
Строка подключения к базе данных ПК «Мастер-Тур»:
<add key = "connectionString" value = "Data Source=ip-адрес сервера базы данных ПК «Мастер-Тур»;Initial Catalog=название базы данных ПК «Мастер-Тур;User ID=логин пользователя ПК «Мастер-Тур»;Password=пароль пользователя ПК «Мастер-Тур»"/>
Настройка
После установки сервис интеграции (например «Сервис интеграции с платежной системой Название_Системы») доступен по адресу
http://ip-адрес сервера Мастер-Веб/Finance/FinanceService.asmx
.
Настройки в файле WEB.CONFIG
Дополнительные настройки, задаются в файле web.config
, находящемся в папке Finance.
№ | Описание | Значение | Настройка |
---|---|---|---|
1 | Определяет тип платежной операции. Тип платежной операции так же может задаваться в настройке SYSPaymentOperationId в таблице SystemSettings. В таком случае в настройке PaymentOperationId задается название настройки из таблицы SystemSettings. Обязательная настройка. |
Идентификатор типа операции - поле PO_Id из таблицы [PaymentOperations] .Либо название настройки SYSPaymentOperationId из таблицы [SystemSettings] .
|
<add key="PaymentOperationId" value="1" />
|
2 | Определяет тип платежной системы при сохранении платежей.
Информация о типе платежной системы записывается в историю по путевке. |
Название платежной системы:
Внимание! По умолчанию данная настройка имеет значение none. Но с этим значением сервис работать не может. Для работы сервиса необходимо указать в ней одно из допустимых значений. |
<add key="PaymentSystem" value="TourPay"/>
|
3 | Определяет время действия идентификатора аутентифации (token). | Время действия (в минутах). | <add key="TokenExpireTime" value="10</span>" />
|
4 | Включение режима записи нового платежа в систему «Мастер-Финанс». При этом в ПК «Мастер-Тур» платежи не сохраняются. | - true - включена запись платежей в «Мастер-Финанс»;
- false или отсутствие настройки - выключает запись платежей в «Мастер-Финанс». |
<add key="AddPaymentsToMasterFinance" value="true"/>
|
5 | Настройка, определяющая дату, на которую должен подбираться курс валют для пересчета суммы к оплате. |
Обработка настройки, начиная с релиза 9220SP31.
Обработка настройки до релиза 9220SP31.
|
<add key="courseExchangeDate" value="orderdate"/>
|
6 | Настройка, позволяющая включить механизм логирования. (Начиная с версии 2009.2.20.31, данная настройка не используется). |
- true — система логирования включена;
- false или отсутствие настройки — логирование выключено. |
<add key="UseLog" value="true"/>
|
7 | Настройка определяющая филиал, с которым будет создан платеж. |
|
<add key="PaymentFilialSource" value="CurrentUser"/>
|
8 | Настройка определяющая типы платежей, при которых разрешена оплата путевки через сервис. | Типы платежей через запятую - поле PT_KEY из таблицы [Paymenttype] (через запятую).
|
<add key="allowedPaymentTypes" value="4"/>
|
9 | Настройка, указывающая что в качестве лица, от которого принята оплата надо всегда использовать представителя агентства (DUP_USER). | - true - в качестве лица, от которого принята оплата всегда указывается ФИО представителя агентства (поле US_FULLNAME из таблицы [DUP_USER] .
- false или отсутствии настройки - работает стандартный механизм выбора лица, от которого принят платеж. |
<add key="useDupUserAsPayer" value="true"/>
|
10 | Настройка, определяющая какую информацию будет выводить метод GetPaymentInformation - полную или сокращенную. | - true - возвращается полная информация по платежу.
- false или отсутствии настройки - возвращается только информация о том, есть ли такой платеж по путевке. |
<add key="paymentInformationReturnEnabled" value="true"/>
|
11 | Настройка, определяющая партнеров - покупателей путевки, для которых можно проводить платеж. | Ключи партнеров через запятую - поле PR_KEY в таблице [Partners] .
Если настройка отсутствует или значение не указано, то можно проводить платеж по любой путевке. |
<add key="allowedPartnerKeys" value="0,10762"/>
|
12 | Настройка адреса платежного сервиса. Обязательная настройка. Обрабатывается с релиза 2009.2.21. |
По умолчанию указан локальный компьютер и стандартный порт. Если служба установлена на другом компьютере, то необходимо указать его ip-адрес и порт. Если на компьютере, где устанавливается сервис, стандартный порт 8080 занят, то необходимо указать другой свободный порт. | <add key="PaymentSignatureServiceAddress" value="http://localhost:8080/PaymentSignatureServiceHost/FinanceService/"/>
|
13 | Определяет, будет ли метод GetReservationInfo выводить информацию по путевке. | - true - метод GetReservationInfo выводит данные по путевке
- false или отсутствие настройки метод GetReservationInfo не выводит данные по путевке |
<add key="allowToGetReservationInfo" value="true"/>
|
Подготовка данных
Проверка заявок и проведение платежа через платежную систему в базу туроператора осуществляется по оформленным путевкам. У путевки должен быть зафиксирован курс валюты, т.е. в истории путевки должно присутствовать сообщение "Фиксация курса".
Логирование
Для детализации ошибок, которые могут возникнуть при работе web-сервиса (например, когда методы web-сервиса возвращают значение ErrorCode 2) можно включить логирование.
Начиная с релиза 2009.2.20.31 изменились настройки логирования
В секции <configSections>
надо добавить строку (если она отсутствует):
<section name="loggerSection" type="Megatec.ConfigLogic.Loggers.LoggersSection, Megatec.ConfigLogic" />
Далее (после секции <configSections>
) прописывается секция <loggerSection>
:
<loggerSection>
<Loggers path="Logs\">
<Logger level="ALL" name="ErrorLog"/>
<Logger level="ALL" name="MasterWebLog"/>
</Loggers>
</loggerSection>
|
- Путь к папке лог-файлов прописывается в секции Loggers path.
- Включение логирования осуществляется в секции Logger level. Возможные значения: ALL или OFF.
Предыдущий вариант настройки логирования (до релиза 2009.2.20.31)
В секции <configSections>
надо добавить строку (если она отсутствует):
<section name="log4net" type="log4net.Config.Log4NetConfigurationSectionHandler, log4net" />
Далее (после секции <configSections>
) прописывается секция <log4net>
:
<log4net>
<appender name="ExceptionLogger" type="log4net.Appender.FileAppender">
<param name="File" value="Logs\\ExceptionLogger.txt" />
<param name="AppendToFile" value="true" />
<layout type="log4net.Layout.PatternLayout">
<param name="ConversionPattern" value="%date [%thread] %-5level [%ndc] - %message %newline %exception" />
</layout>
</appender>
<logger name="ExceptionLogger">
<param name="Threshold" value="ALL" />
<appender-ref ref="ExceptionLogger" />
</logger>
<appender name="ServiceLogger" type="log4net.Appender.FileAppender">
<param name="File" value="Logs\\Megatec.Web.Services.Finance.FinanceService.txt" />
<param name="AppendToFile" value="true" />
<layout type="log4net.Layout.PatternLayout">
<param name="ConversionPattern" value="%date [%thread] %-5level [%ndc] - %message %newline %exception" />
</layout>
</appender>
<logger name="ServiceLogger">
<param name="Threshold" value="ALL" />
<appender-ref ref="ServiceLogger" />
</logger>
</log4net>
|
- Путь к лог-файлу прописывается в секции File.
<param name="File" value="Logs\\ExceptionLogger.txt" />
- Включение логирования осуществляется в секции Threshold.
Возможные значения: ALL или OFF.<param name="Threshold" value="ALL" />
- С помощью настройки maximumFileSize можно ограничить размер лог-файла. В таком случае будут автоматически удаляться старые записи.
<maximumFileSize value="10240KB" />
Работа в системе
Аутентификация (метод «GetUserToken»)
Метод возвращает строку - идентификатор аутентификации, который используется для подтверждения авторизации при вызове методов web-сервисов.
Сигнатура метода
public TokenResult GetUserToken(string userLogin, string userPassword)
Описание принимаемых методом параметров
- userLogin - имя пользователя on-line системы бронирования ПК «Мастер-Web»;
- userPassword - пароль пользователя on-line системы бронирования ПК «Мастер-Web».
Возвращаемые значения
Метод возвращает результат своей работы в виде класса TokenResult. Корректность результата проверяется значением поля ErrorCode данного класса:
- 0 - результат корректный;
- 2 – внутренняя ошибка;
- 5 - неправильный логин или пароль.
Описание класса:
public class TokenResult
{
public int ErrorCode;
public string Token;
}
|
- ErrorCode - код результата;
- Token - идентификатор аутентификации.
Проверка заявки (метод «CheckReservation»)
Описание метода
Данный метод предназначен для проверки наличия заявки в БД и определения ее стоимости.
Сигнатура метода
public AmountSum CheckReservation(string userToken, string dgCode)
Описание принимаемых методом параметров
- userToken - идентификатор аутентификации, полученный при вызове метода GetUserToken;
- dgCode - строковая переменная, представляющая собой код проверяемой путевки.
Возвращаемые значения
Метод возвращает результат своей работы в виде класса AmountSum. Корректность результата проверяется значением поля ErrorCode данного класса:
- 0 – результат корректный, в полях возвращены корректные значения;
- 1 – заявка не найдена в БД;
- 2 – внутренняя ошибка;
- 3 – заявка была аннулирована;
- 4 – путевка уже оплачена;
- 6 – некорректный или устаревший идентификатор аутентификации (token);
- 8 – запрещено создавать платеж по путевке, так как есть платежи с типами, не указанными в настройке allowedPayments;
- 9 – запрещено создавать платеж по путевке, так как покупатель путевки не указан в настройке allowedPartnerKeys.
Описание класса:
public class AmountSum
{
public double Amount
public string RateCode
public double NationalCurrencyPrice
public string NationalRateCode
public int ErrorCode
public int FilialKey
public DateTime BeginTourDate
public DateTime EndTourDate
}
|
- Amount - сумма к оплате в валюте тура;
- RateCode - iso-код валюты тура;
- NationalCurrencyPrice - сумма к оплате в национальной валюте;
- NationalRateCode - iso-код национальной валюты;
- ErrorCode - код результата;
- FilialKey - ключ филиала, который создал заявку;
- BeginTourDate - дата начала тура;
- EndTourDate - дата окончания тура.
- MainTouristFIO - фамилия и инициалы главного туриста.
Проведение платежа по заявке (метод «CreatePayment»)
Описание метода
Данный метод предназначен для создания платежа по путевке в финансовом блоке ПК «Мастер-Тур».
Сигнатура метода
public int CreatePayment(string userToken, DateTime date, Decimal sum, string currencyIsoCode, string reservationCode, string externalPaymentId)
Описание принимаемых методом параметров
- userToken - идентификатор аутентифкации;
- date – дата проведения платежа;
- sum – сумма платежа;
- currencyIsoCode – ISO-код валюты, в которой осуществляется платеж;
- reservationCode – номер путевки;
- externalPaymentId – идентификатор платежа во внешней системе.
Возвращаемые значения
Данный метод возвращает целочисленное значение обозначающее результат выполнения операции:
- 0 – операция выполнена успешно, платеж проведен;
- 1 – заявка не найдена в БД;
- 2 – внутренняя ошибка при создании платежа;
- 3 - заявка была аннулирована;
- 4 - путевка уже оплачена;
- 6 - некорректный или устаревший идентификатор аутентификации(token).
- 7 - платеж с таким идентификатором уже существует.
При этом в БД создается платеж по выбранной путевке.
Проверка существования платежа/информация по платежу (метод «GetPaymentInformation»)
Описание метода
Данный метод предназначен для проверки существования платежа и получения информации по платежу.
Поведение метода зависит от значения настройки paymentInformationReturnEnabled.
Сигнатура метода
public PaymentInformationResult GetPaymentInformation(String userToken, String reservationCode, String externalPaymentId)
Описание принимаемых методом параметров
- userToken - идентификатор аутентифкации;
- reservationCode – номер путевки;
- externalPaymentId – идентификатор платежа во внешней системе.
Возвращаемые значения
Метод возвращает результат своей работы в виде класса PaymentInformationResult. Корректность результата проверяется значением поля ErrorCode данного класса:
- 0 – результат корректный, в полях возвращены корректные значения;
- 2 – внутренняя ошибка;
Описание классов:
public class PaymentInformationResult
{
/// <summary>
/// Признак наличия платеже
/// </summary>
public Boolean IsPaymentExists { get; set; }
/// <summary>
/// Краткая информация по платежу
/// </summary>
public PaymentsShortInformation PaymentsShortInformation { get; set; }
/// <summary>
/// Код ошибки
/// </summary>
public Int32 ErrorCode { get; set; }
}
|
- IsPaymentExists - показывает, есть ли запрошенный платеж:
- true - платеж с указанным идентификатором по указанной путевке существует.
- false - запрошенного платежа нет.
- PaymentsShortInformation - информация по платежу.
Описание класса:
public class PaymentsShortInformation
{
/// <summary>
/// Id платежа в системе МТ
/// </summary>
public Int32 InternalPaymentId { get; set; }
/// <summary>
/// Номер путевки по платежу
/// </summary>
public String DogovorCode { get; set; }
/// <summary>
/// Сумма платежа
/// </summary>
public Decimal PaymentSum { get; set; }
/// <summary>
/// Сумма платежа в нац.валюте
/// </summary>
public Decimal PaymentNationalSum { get; set; }
/// <summary>
/// Валюта платежа
/// </summary>
public String PaymentRateISOCode { get; set; }
/// <summary>
/// Дата проведения платежа
/// </summary>
public DateTime CreateDate { get; set; }
}
|
- InternalPaymentId - идентификатор платежа в системе ПК «Мастер-Тур» (поле PM_Id в таблице
[Payments]
); - DogovorCode - номер путевки;
- PaymentSum - сумма к оплате;
- PaymentNationalSum - сумма к оплате в национальной валюте;
- PaymentRateISOCode - ISO-код валюты платежа;
- CreateDate - дата и время создания платежа.
- InternalPaymentId - идентификатор платежа в системе ПК «Мастер-Тур» (поле PM_Id в таблице
- ErrorCode - код результата.
Получение информации по заявке (метод «GetReservationInfo»)
Описание метода
Данный метод предназначен для выгрузки данных по путевке из базы данных ПК «Мастер-Тур» для проведения платежа.
Сигнатура метода
public ReservationInformationResult GetReservationInfo(string userToken, string dgCode)
Описание принимаемых методом параметров
- userToken - идентификатор аутентификации, полученный при вызове метода GetUserToken;
- dgCode - строковая переменная, представляющая собой код проверяемой путевки.
Возвращаемые значения
Метод возвращает результат своей работы в виде класса ReservationInformationResult. Корректность результата проверяется значением поля ResultCode данного класса:
- 0 – результат корректный, в полях возвращены корректные значения;
- 2 – внутренняя ошибка;
- 5 - некорректный логин или пароль;
- 6 - некорректный или устаревший идентификатор аутентификации(token).
Ниже приводится описание класса.
public class ReservationInformationResult
{
public double Price { get; set; }
public double PriceNational { get; set; }
public double DiscountSum { get; set; }
public double DiscountSumNational { get; set; }
public double PriceToPay { get; set; }
public double PriceToPayNational { get; set; }
public string IsoRateCode { get; set; }
public string IsoRateCodeNational { get; set; }
public int ResultCode { get; set; }
public int? FilialKey { get; set; }
public DateTime TourDate { get; set; }
public DateTime TourDateEnd { get; set; }
public string CountryName { get; set; }
public string TourName { get; set; }
public List<TouristFinanceInfo> ReservationTourists { get; set; }
public List<string> ReservationServices { get; set; }
}
|
- Price - полная стоимость тура (в валюте тура);
- PriceNational - полная стоимость тура (в нац. валюте);
- DiscountSum - скидка по путевке (в валюте тура);
- DiscountSumNational - скидка по путевке (в нац. валюте);
- PriceToPay - cумма к оплате в валюте тура (PriceToPay = Price - DiscountSum);
- PriceToPayNational - cумма к оплате в национальной валюте;
- intIsoRateCode - iso-код валюты тура;
- IsoRateCodeNational - iso-код национальной валюты;
- ResultCode - код результата;
- FilialKey - ключ филиала, который создал заявку;
- TourDate - дата начала тура;
- TourDateEnd - дата окончания тура;
- CountryName - название страны на русском языке;
- ReservationTourist - Массив туристов по путевке;
- FullName - ФИО туриста на русском языке;
- FullNameLat - имя туриста на английском языке;
- BirthDate - дата рождения туриста;
- IsMain - параметр, показывающий главного туриста;
- ReservationServices - массив услуг в путевке.