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

Материал из Megatec
Версия от 10:37, 4 июля 2014; Achkasov (обсуждение | вклад) (Создание виртуального каталога)
Перейти к: навигация, поиск

Версия статьи от 4-07-2014. Для перехода на версию статьи, соответствующую используемой Вами версии программы, нажмите ссылку в таблице ниже:

Более ранние версии:
До 2009.2.12 включительно
До 2009.2.15 включительно
До 2009.2.19 включительно
До 2009.2.20.13 включительно
До 2009.2.20.14 включительно


Содержание

Введение

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

  • TourPay
  • PayTravel

Ссылка на тестовый сервис

С работой тестового сервиса для интеграции с платежной системой вы можете ознакомиться на нашем демо-сервере.

Установка

Для установки Сервиса для интеграции с платежной системой нужно создать директорию 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
Администрирование - Диспетчер служб 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 Определяет тип платежной системы при сохранении платежей.

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

Название платежной системы - одно из четырех значений:
  • Leader;
  • Qiwi;
  • TourPay;
  • Paytravel.

Внимание! По умолчанию данная настройка имеет значение none. Но с этим значением сервис работать не может. Для работы сервиса необходимо указать в ней одно из допустимых значений.

<add key="PaymentSystem" value="TourPay"/>
3 Определяет время действия идентификатора аутентифации (token). Время действия (в минутах).
<add key="TokenExpireTime" value="10</span>" />
4 Включение режима записи нового платежа в систему «Мастер-Финанс». При этом в ПК «Мастер-Тур» платежи не сохраняются. - true - включена запись платежей в «Мастер-Финанс»;

- false или отсутствие настройки - выключает запись платежей в «Мастер-Финанс».

<add key="AddPaymentsToMasterFinance" value="true"/>
5 Настройка, определяющая дату, на которую должен подбираться курс валют для пересчета суммы к оплате.
  • orderdate — дата оформления заявки;
  • today — курс на текущую дату;
  • confirmdate — курс на дату подтверждения заявки (если подтверждения путевки еще не было, либо курс на дату подтверждения не заведен, то будет отображаться курс на текущую дату);
  • fixationdate — курс на дату фиксации.
<add key="courseExchangeDate" value="orderdate"/>
6 Настройка, позволяющая включить механизм логирования. - true — система логирования включена;

- false или отсутствие настройки — логирование выключено.

<add key="UseLog" value="true"/>
7 Настройка определяющая филиал, с которым будет создан платеж.
  • Reservation — филиал путевки;
  • CurrentUser или отсутствие настройки — филиал пользователя, от имени которого работает сервис.
<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"/>

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

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

Логирование

Для детализации ошибок, которые могут возникнуть при работе web-сервиса (например, когда методы web-сервиса возвращают значение ErrorCode 2) можно включить логирование.

В секции <configSections> надо добавить строку:

<section name="log4net" type="log4net.Config.Log4NetConfigurationSectionHandler, log4net" />

Далее (после секции <configSections>) прописывается секция <log4net>:

<log4net>
   <appender name="ExceptionLogger" type="log4net.Appender.FileAppender">
     <param name="File" value="C:\\MasterTourLogs\\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>
 </log4net>

Красным цветом выделен путь к файлу лога. Здесь может быть указан произвольный путь.

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

Аутентификация (метод «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 - дата и время создания платежа.
  • ErrorCode - код результата.