Интерфейс для оператора (UEGat…
  • RSS Feed

Last modified on 26.05.2015 10:41 by User.

Tags:

Интерфейс для оператора (UEGate)

Порядок информационного обмена

1.1. Запросы от ПЦ Агента передаются путем передачи данных на веб-сервер Оператора по протоколу HTTPS (с использованием 128 разрядного шифрования), с использованием аутентификации клиента одним или несколькими выбранными способами (“Basic” аутентификация запроса с указанием логина и пароля Агента, аутентификация по клиентскому сертификату, аутентификация по логину и паролю Агента переданными  в строке GET запроса).

1.2. Веб-сервер Оператора обеспечивает авторизацию запросов Агента по сетевому адресу передающей стороны со стороны Агента и данным аутентификации.

1.3. Запросы могут поступать параллельно, т. е. очередной запрос может быть направлен до получения ответа на предыдущий запрос. Длительность таймаута до получения ответа не превышает 30 секунд.

1.4. Веб-сервер Оператора возвращает результат обработки запроса (ответ) Агента, в виде XML-документа.

1.5. Запросы Агента передаются с использованием метода передачи параметров запроса GET, с использованием, в случае необходимости, URL кодирования.

1.6. Запросы Агента и ответы от веб-сервера Оператора  кодируются с использованием кодировки Windows-1251.

1.7. Все запросы Агента производятся по одному адресу (URL) указанному Оператором.

1.8. Порядок произведения операции регистрации платежа Агентом следующий:

1.8.1. Агент передает на веб-сервер Оператора запрос на проверку возможности регистрации платежа, указывая получателя платежа, идентифицируемому по уникальному набору атрибутов, сумму платежа и назначение платежа. Веб-сервер Оператора возвращает Агенту ответ, содержащий код, указывающий на возможность регистрации платежа, либо на причину отсутствия возможности. В случае если Агент получает ответ, содержащий код, указывающий на возможность регистрации платежа, Агент переходит к следующему шагу. В обратном случае Агент считает, что регистрация платежа невозможна.

1.8.2. Агент передает на веб-сервер Оператора запрос на регистрацию платежа, указывая получателя платежа, идентифицируемому по уникальному набору атрибутов, сумму платежа, назначение платежа, уникальный номер платежа в системе Агента, дату и время платежа в системе Агента. При этом сочетание номера платежа, дата и время платежа являются уникальным идентификатором в системе Оператора. Веб-сервер Оператора возвращает Агенту ответ, содержащий код, указывающий на результат регистрации платежа в системе Оператора и уникальный номер платежа в системе Оператора, в случае успешной регистрации платежа. Если в течение времени, установленного таймаутом, Агент не получает ответа от Оператора содержащий код, указывающий на успешную регистрацию платежа Оператором, то передает запрос повторно, до тех пор пока не получит правильный ответ, подтверждающий факт регистрации платежа. При повторении конкретного запроса на регистрацию платежа Оператор возвращает Агенту всегда одинаковый ответ, в случае если регистрация платежа произошла, при этом, не регистрируя платеж повторно.

1.9. Оператор гарантирует, что при получении положительного ответа на запрос на проверку возможности регистрации платежа, запрос на регистрацию платежа будет выполнен успешно, в любом случае.

1.10. Важно. В данном протоколе не может быть ошибок с "неопределенным" статусом в ответ на запрос регистрации платежа. Любая ошибка должна однозначно говорить о статусе платежа - либо принят, либо нет. В случае получения "временной" ошибки в поле <RESULTCODE>, как то - "Сервис перегружен", "База недоступна" и т.д., ПЦ Агента не может повторить запрос на проведение платежа с такими же реквизитами. Единственный способ сделать это, отвечать ошибкой HTTP протокола, например, 500. Только в этом случае ПЦ Агента сможет повторить запрос на проведение платежа с такими же реквизитами.

Следовательно, необходимо либо не возвращать "временных" ошибок, либо реализовывать временные ошибки с помощью ошибок HTTP протокола.

1.11. Ежедневный итоговый реестр:

1.11.1. Агент, ежедневно, в установленное по согласованию с Оператором, время передает Оператору итоговый реестр принятых платежей за прошедшие полные сутки (с 00:00:00 часов до 00:00:00 часов следующего дня). Оператор при получении от Агента итогового реестра формирует список платежей на эту же дату и производит сравнение с итоговым реестром Агента.

1.11.2. В случае обнаружения Оператором расхождений с итоговым реестром Агента, Оператор связывается с представителями Агента для выяснения причин расхождений и их устранения.

Форматы запросов и ответов веб-сервера Оператора

2.1. Запросы должны содержать только те параметры, которые являются необходимыми и достаточными для конкретного типа запроса.

2.2. Используемые в запросах параметры:

Название

Назначение

Тип

Размер

Комментарии

LOGIN

Логин Агента

Строка

Не более 20

Необязательное поле. В случае авторизации по логину/паролю  - обязательное.

PASS

Пароль Агента

Строка

Не более 20

Необязательное поле. В случае авторизации по логину/паролю - обязательное. 

TYPE

Тип запроса

Число

1

Обязательное поле.

Допустимые значения:

1 – запрос на проверку возможности регистрации платежа;

2 - запрос на регистрацию платежа.

CODE1

Идентификатор 1 получателя платежа

Строка

Не более 255

Обязательное поле.

CODE2

Идентификатор 2 получателя платежа

Строка

Не более 255

Опционально: если не используется, передавать пустую строку.

CODE3

Идентификатор 3 получателя платежа

Строка

Не более 255

Опционально: если не используется, передавать пустую строку

AMOUNT

Сумма платежа в копейках

Число

Не более 9

Обязательное поле.

PAYTYPE

Тип или назначение платежа

Число

Не более 3

Опционально.

PAYID

Номер платежа в системе Агента

Число

Не более 20

Обязательное поле в запросе регистрации платежа.

DATE

Дата платежа в системе Агента

Строка

14

Обязательное поле в запросе регистрации платежа.Формат: YYYYMMDDHHMMSS

RECEIPT

Номер чека

Строка

20

Опционально: если не используется, передавать пустую строку

TID

Идентификатор терминала

Строка

20

Необязательное поле.

2.3. Используемые поля в ответах:

Название

Назначение

Тип

Размер

Комментарии

RESULTCODE

Код результата выполнения запроса

Не отрицательное число

Не более 4

Обязательное поле.

0 - считается положительным результатом выполнения запроса, все остальные значения - кодом ошибки

RESULTMESSAGE

Описание результата выполнения запроса

Строка

Не более 255

Необязательное поле.

DATE

Дата и время выполнения запроса на стороне Оператора

Строка

14

Обязательное поле в ответе на запрос регистрации платежа. 

Формат: YYYYMMDDHHMMSS

PAYID

Номер платежа в системе Оператора

Число

Не более 20

Обязательное поле в ответе на запрос регистрации платежа.

ADDINFO

Дополнительная информация передаваемая Оператором Агенту в рамках платежа

Строка

Не более 255

Необязательное поле.

Может, к примеру, содержать ФИО получателя платежа, задолженность получателя платежа, и т.п.

2.4. Проверка возможности регистрации платежа

2.4.1. Запрос

https://<serviceUrl>?[LOGIN=value&PASS=value&]TYPE=1&[PAYTYPE=value&]CODE1=value[&CODE2=value[&CODE3=value]]&AMOUNT=value

2.4.2. Ответ

<?xml version="1.0" encoding="windows-1251" ?> 
<RESPONSE>
  <RESULTCODE>value</RESULTCODE> 
  <RESULTMESSAGE>value</RESULTMESSAGE> 
  <DATE>value</DATE>
  <ADDINFO>value</ADDINFO>
</RESPONSE>

2.5. Регистрация платежа

2.5.1. Запрос

https://<serviceUrl>?[LOGIN=value&PASS=value&]TYPE=2&[PAYTYPE=value&]CODE1=value[&CODE2=value[&CODE3=value]]&AMOUNT=value&PAYID=value&DATE=value[&RECEIPT=value[&TID=value]]

2.5.2. Ответ

Положительный:

<?xml version="1.0" encoding="windows-1251" ?> 
<RESPONSE>
  <RESULTCODE>0</RESULTCODE> 
  <RESULTMESSAGE>value</RESULTMESSAGE>
  <DATE>value</DATE> 
  <PAYID>value</PAYID>
</RESPONSE>

Отрицательный:

<?xml version="1.0" encoding="windows-1251" ?> 
<RESPONSE>
  <RESULTCODE>value</RESULTCODE> 
  <RESULTMESSAGE>value</RESULTMESSAGE>
  <DATE>value</DATE> 
</RESPONSE>

Требования к итоговому реестру принятых платежей

3.1. Итоговый реестр принятых платежей – текстовый файл, содержащий список платежей, зарегистрированных Оператором, по запросам Агента, за отчетную дату.

3.2. В итоговом реестре должны содержаться все успешно зарегистрированные платежи за один календарный день в период времени с 00:00:00 часов по 00:00:00 часов следующего дня часов.

3.3. Файлы с итоговыми реестрами принятых платежей опционально защищаются (шифруются и/или подписываются) посредством PGP и передаются по электронной почте Оператору.

3.4. Имя файла должно содержать дату и название платежной системы Агента в формате <YYYYMMDD><PaySystemName>.pgp

3.5. Файл содержит данные в кодировке Windows-1251.

3.6. Файл состоит из строк, разделенных символами “перевод строки”, “возврат каретки”.

3.7. Все строки в файле содержат одинаковое количество полей разделенных между собой символом “точка с запятой”.

3.8. Строка имеет следующую структуру:

[PAYTYPE;]CODE1[;CODE2[;CODE3]];AMOUNT;PAYIDA;PAYIDOP;DATE[;RECEIPT[;TID]] 

,где:

PAYTYPE - тип или назначение платежа;

CODE1 - идентификатор 1 получателя платежа;

CODE2 - идентификатор 2 получателя платежа;

CODE3 - идентификатор 3 получателя платежа;

AMOUNT – сумма платежа в копейках;

PAYIDA – номер платежа в системе Агента;

PAYIDOP – номер платежа в системе Оператора;

DATE – дата платежа в системе Агента;

Данные оператора, необходимые Агенту для включения его в систему

4.1. Оператор предоставляет информацию по следующим пунктам:

- за какие услуги будут приниматься платежи; необходимо для того, чтобы понять каким образом будут разделяться платежи по нескольким услугам: будут ли это различные URL,

будет ли это выполнение запросов под различными учетными записями в системе оператора (определяемых значением параметра LOGIN в запросе) или это будет определяться параметром PAYTYPE протокола) 

- количество, название и формат (длина, допустимые символы и т.п.) идентификаторов получателя платежа

- ограничения на максимальную и минимальную сумму платежа по всем типам услуг

- полный путь выполнения запросов на сервер Оператора (хост, порт, путь к приложению)

- тип используемой аутентификации Агента (не используется, http basic access, логин/пароль в строке запроса (параметры LOGIN и PASS), сертификат)

- список с кодами ошибок, возвращаемых Агенту в рамках работы по данному протоколу,

то есть те, которые будут возвращаться в параметре RESULTCODE ответа Оператора, с описанием ошибки.