|
Порядок электронного документооборота
Данный протокол описывает порядок информационного взаимодействия между СЕРВИС-ПРОВАЙДЕРОМ (поставщиком услуг) и системой приема платежей АГЕНТА (далее Система). Взаимодействие заключается в обмене информацией о платежах за услуги СЕРВИС-ПРОВАЙДЕРА, поступивших в Систему.
Взаимодействие Системы и СЕРВИС-ПРОВАЙДЕРА строится в режиме запрос-ответ, где инициатором запроса всегда является Система, а отвечающей стороной являетсяСЕРВИС-ПРОВАЙДЕР. Запросы и ответы состоят из набора полей, которые описаны ниже.
СОСТОЯНИЕ И АТТРИБУТЫ ПЛАТЕЖА
По своему состоянию платеж может считаться:
- отсутствующим (нет никакой информации о платеже)
- зачисленным (после успешного запроса зачисления платежа)
- аннулированным (после успешного запроса аннулирования)
- Реквизиты клиента (передает Система). Реквизиты однозначно идентифицируют клиента. Если реквизит один, размещается в поле account. Если реквизитов несколько, они определенным алгоритмом упаковываются в поле account, либо создается несколько полей (имена полей оговариваются отдельно).
- Сумма платежа (передает Система). Указывается с точностью до копеек.
- Дата и время принятия платежа Системой (передает Система). Указывается с точностью до секунд.
- Уникальный идентификатор платежа (передает Система). Платежи, у которых все идентификаторы разные считаются разными, независимо от совпадения остальных атрибутов. Уникальный идентификатор однозначно определяет все остальные атрибуты платежа.
- Дата и время зачисления платежа СЕРВИС-ПРОВАЙДЕРОМ (определяет СЕРВИС-ПРОВАЙДЕР во время зачисления). Данный атрибут имеет место только для зачисленного платежа.
- Дата и время аннуляции платежа СЕРВИС-ПРОВАЙДЕРОМ (определяет СЕРВИС-ПРОВАЙДЕР во время аннуляции). Данный атрибут имеет место только для аннулированного платежа.
Все атрибуты и состояние платежа должны сохраняться как на стороне СЕРВИС-ПРОВАЙДЕРА, так и на стороне Системы. Если СЕРВИС-ПРОВАЙДЕР не может сохранять дату и время принятия платежа Системой, либо дату и время зачисления платежа СЕРВИС-ПРОВАЙДЕРОМ, то по взаимной договоренности Система и СЕРВИС-ПРОВАЙДЕР могут исключить данный атрибут из логики взаимодействия.
ОПИСАНИЕ ЗАПРОСОВ:
Каждый запрос Системы и ответ СЕРВИС-ПРОВАЙДЕРА состоит из набора именованных полей. Протокол предусматривает 4 типа запросов и ответов, в каждом из которых определен свой набор полей.
Запрос "check". Предназначен для проверки возможности принятия платежа. Успешный ответ СЕРВИС-ПРОВАЙДЕРА подтверждает возможность принятия СЕРВИС-ПРОВАЙДЕРОМ платежа с указанными в запросе реквизитами.
Поля запроса:
- account - реквизит
- sum - сумма платежа
- timestamp - дата/время формирования запроса
Поля ответа:
- result - результат (допустимы E*, S1, F1, F2, F3, F4)
- reason - уточняющий комментарий отказа для СП (не обязателен)
- account - копия из запроса
- sum - копия из запроса
- timestamp - копия из запроса
Запрос "payment". Предназначен для зачисления платежа. Успешный ответ СЕРВИС-ПРОВАЙДЕРА подтверждает зачисление СЕРВИС-ПРОВАЙДЕРОМ платежа с уникальным идентификатором и реквизитами, указанными в запросе.
Поля запроса:
- id - уникальный идентификатор платежа на стороне Системы
- pay_time - дата/время принятия платежа системой (наличие по договоренности)
- account - реквизит
- sum - сумма платежа
- timestamp - дата/время формирования запроса
Поля ответа:
- result - результат (допустимы E*, S1, F1, F2, F3, F4, F5, F7)
- reason - уточняющий комментарий отказа для СП (не обязателен)
- accepted - дата/время зачисления платежа СЕРВИС-ПРОВАЙДЕРОМ (наличие по договоренности, указывается в случае S1)
- id - копия из запроса
- pay_time - копия из запроса (наличие по договоренности)
- account - копия из запроса
- sum - копия из запроса
- timestamp - копия из запроса
Запрос "status". Предназначен для получения Системой реквизитов принятого платежа. Ответ СЕРВИС-ПРОВАЙДЕРА с результатом S1 подтверждает наличие принятого платежа с уникальным идентификатором, указанным в запросе.
Поля запроса:
- id - уникальный идентификатор платежа
- timestamp - дата/время формирования запроса
Поля ответа:
- result - результат (допустимы E*, S1, S2, F6)
- account - реквизит найденного платежа (присутствует в случае успешного ответа)
- sum - сумма найденного платежа (присутствует в случае успешного ответа)
- pay_time - дата/время принятия платежа Системой (наличие по договоренности)
- accepted - дата/время зачисления найденного платежа (присутствует в случае успешного ответа)
- revoked - дата/время аннулирования найденного платежа (присутствует в случае ответа с результатом S2)
- reason - уточняющий комментарий отказа для СЕРВИС-ПРОВАЙДЕРА (не обязателен)
- id - копия из запроса
- timestamp - копия из запроса
Запрос "revoke". Предназначен для аннулирования ранее зачисленного платежа. Успешный ответ СЕРВИС-ПРОВАЙДЕРА подтверждает аннулирование СЕРВИС-ПРОВАЙДЕРОМ ранее зачисленного платежа с уникальным идентификатором, указанным в запросе.
Поля запроса:
- id - уникальный идентификатор платежа, подлежащий аннулированию
- comment - комментарий к операции аннулирования (не обязателен)
- timestamp - дата/время формирования запроса
Поля ответа:
- result - результат (допустимы E*, S2, F6, F7, F8)
- reason - уточняющий комментарий отказа для СЕРВИС-ПРОВАЙДЕРА (не обязателен)
- revoked - дата/время аннулирования платежа СЕРВИС-ПРОВАЙДЕРОМ (указывается в случае S2)
- id - копия из запроса
- comment - копия из запроса
- timestamp - копия из запроса
В запрос Системы (и, соответственно, в ответСЕРВИС-ПРОВАЙДЕРА) может быть добавлено поле service, которое преусмотрено для указания оплачиваемой услуги в том случае, если СЕРВИС-ПРОВАЙДЕР предоставляет возможность оплаты нескольких услуг.
ФОРМАТ ПОЛЕЙ
account - формат оговаривается отдельно между Системой и СЕРВИС-ПРОВАЙДЕРОМ
sum - число с 2 фиксированными знаками после запятой, разделитель - точка
id - целое 32-битное число, от 0 до 2^32-1
timestamp, pay_time, accepted, revoked - дата/время в формате ISO с точностью до секунд, YYYY-MM-DDTHH:MM:SS±hh
result - [ESF][0-9]{1,2}
reason, comment - строка до 256 символов
РЕЗУЛЬТАТЫ (поле result):
E1 - запрос не распознан
E2 - технические трудности обработки запроса
E3 - подпись запроса неверна
E4 - результат операции еще не известен
S1 - успешно, платеж считается зачисленным
S2 - успешно, платеж считается аннулированным
F1 - отказ, сумма меньше минимальной допустимой
F2 - отказ, сумма больше максимальной допустимой
F3 - отказ, клиент с указанными реквизитами не найден
F4 - отказ, платеж невозможен (но клиент с указкнными реквизитами найден)
F5 - отказ, платеж с указанным id уже проведен
F6 - отказ, платеж с указанным id не найден
F7 - отказ, платеж с указанным id уже аннулирован
F8 - отказ, аннулирование не возможно
АУТЕНТИФИКАЦИЯ ЗАПРОСОВ И ОТВЕТОВ
Для аутентификации сторон используется электронный аналог собственноручной подписи (далее просто "подпись"), которым подписываются запросы и ответы. Запрос или ответ, подпись которого неверна, должен быть отвергнут с диагностикой ошибки проверки подписи.
В качестве алгоритма подписи используются ассиметричный алгоритм RSA с алгоритмом хеширования MD5 или SHA1. Проверка подписи и ее формирование осуществляется по строке, которая состоит из полей запроса или ответа, за исключением поля sign, в котором передается сама подпись.
Строка, по которой формируется подпись, состоит из подстрок-определений полей, упорядоченных по строковому возрастанию имени поля и соединенных символом '&' (амперсанд). Подстроки-определения полей состоят из имени поля и URL-кодированного значения поля, соединенных символом '=' (равно).
Для устранения разногласий между разными стандартами и исключения ошибок в проверки подписи алгоритм URL-кодирования оговаривается отдельно. Используется кодирование всех символов, отличных от алфавитно-цифровых символов, символа '_' (подчеркивания), символа '-' (равно) и символа '.' (точки) в соответствующее шестнадцатеричное представление %XX, где XX является шестнадцатеричным кодом символа.
ТРЕБОВАНИЯ К ШЛЮЗУ
Операция check должна максимально возможно проверить все случаи отказов, которые возможны в payment.
Ответ СЕРВИС-ПРОВАЙДЕРА содержит ВСЕ поля запроса Системы в том неизменном строковом виде, в котором они пришли в запросе. В случае их несовпадения Система не должна обрабатывать такой ответ.
Запросы и ответы с неверной подписью не должны приниматься к обработке ни Системой, ни СЕРВИС-ПРОВАЙДЕРОМ.
ТРАНСПОРТНЫЙ УРОВЕНЬ ПЕРЕДАЧИ ЗАПРОСОВ И ОТВЕТОВ
В качестве транспортного уровня используется протокол HTTP. Поля запроса отправляются методом POST с типом контента (заголовок "Content-Type") "application/x-www-form-urlencoded". Поля и значения ответа возвращаются в теле ответа в аналогичном формате, как и при запросе методом POST, с таким же типом контента.
Для правильного восприятия комментариев в заголовках требуется указывать кодировку значений полей.
В каждом запросе Системы присутствует поле type, которое содержит тип запроса виде строчек check, payment, status или revoke.
В каждом запросе Системы присутствует поле sign, которое содержит подпись запроса в виде шестнадцатеричного дампа двоичных данных подписи (старшие 4 бита байта - первые, подпись формируется в порядке следования байтов).
|
