Протокол взаимодействия с платежной системой

Материал из doc.abonent.plus
Перейти к: навигация, поиск

В данном документе описан регламент технического взаимодействия платежной системы «Абонент» с программным обеспечением агента по приему платежей по протоколу HTTP(S).

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

Термины и определения

Система – платежная система «Абонент».

Агент – организация, осуществляющая прием оплаты через платежную систему «Абонент».

Алгоритм взаимодействия с системой

Взаимодействие с системой осуществляется в режиме запрос – ответ. Инициатором связи является клиентское ПО агента.

Для начала взаимодействия с системой агентом должны быть получены сертификат цифровой подписи и код клиента по приему платежей. Эти данные выдаются при подключении к системе. Запрещается передача этих сведений третьим лицам.

Общее описание допустимых запросов к системе

В функционал программного обеспечения работающего на стороне агента по приему платежей входит:

  1. Возможность выполнения запроса проверки доступности системы.
  2. Возможность получения списка доступных услуг.
  3. Возможность получения информации по лицевому счету для проведения платежа.
  4. Возможность проведения оплаты по указанному лицевому счету и по указанной услуге.

На каждый запрос система возвращает результат выполнения запроса и описание результата выполнения. В случае ошибки, система вернет также расширенное описание ошибки.

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

  • 0 – запрос успешно обработан;
  • -1 – некорректная подпись;
  • -2 – версия протокола не поддерживается;
  • -3 – произошла ошибка обработки запроса.

Кроме того, по определенным типам запросов система может возвращать выходные параметры.

Набор входных и выходных параметров по каждому типу запроса описан в следующих разделах.

Проверить соединение

  1. Входные параметры – код клиента.
  2. Выходные параметры – отсутствуют.

Получить список услуг

  1. Входные параметры – код клиента.
  2. Выходные параметры:
    1. Код услуги или ресурса (в дальнейшем используется для формирования платежа).
    2. Наименование услуги или ресурса.
    3. Код организации, оказывающей услугу или поставляющей ресурс.
    4. Наименование организации, оказывающей услугу или поставляющей ресурс.
    5. Код типа лицевого счета, используемый для идентификации плательщика.
    6. Наименование типа лицевого счета, используемого для идентификации плательщика.
    7. Реквизиты организации для перечисления средств.
    8. Дополнительные поля для формирования платежа.

Получить данные по абоненту

  1. Входные параметры:
    1. Код типа лицевого счета.
    2. Лицевой счет.
  2. Выходные параметры:
    1. Код типа лицевого счета.
    2. Лицевой счет абонента.
    3. Список альтернативных лицевых счетов абонента с указанием типа.
    4. Список услуг абонента с информацией для приема платежа (текущая задолженность, признак наличия счетчика, последние показания счетчика и дата их съема, текущий тариф).

Зарегистрировать платеж

  1. Входные параметры:
    1. Уникальный номер платежа (Guid).
    2. Дата/время.
    3. Примечание.
    4. Другая информация.
    5. Зачисления - список сумм оплат, с разбивкой по услугам, с указанием для каждой услуги:
      • Кода типа лицевого счета.
      • Лицевого счета.
      • Кода услуги.
      • Суммы платежа.
      • Дополнительные параметры (текущие показания счетчика, оплачиваемы объем и т.д.).
  2. Выходные параметры – результат обработки (поставлен в очередь, отклонен и т.д.)

Проверить статус платежа

  1. Входные параметры – уникальный номер платежа (Guid).
  2. Выходные параметры: список зачислений с указанием результатов обработки по каждому из зачислений (отправлено поставщику услуг/находится в очереди на обработку/ошибка и т.д.).

Общая структура взаимодействия

Инициатором обмена является ПО агента по приему платежей. Запросы посылаются через интернет, по протоколу HTTP(S) методом POST. Данные передаются в JSON-формате. Каждый запрос обязательно должен быть подписан с помощью ЭЦП агента.

Запрос должен содержать следующие поля:

  1. ProtocolVersion – версия протокола, строка.
  2. DataFormat- формат данных в поле Data. В настоящее время поддерживается только формат JSON, что соответствует значению 0 в данном поле.
  3. SignedData – подписываемые данные, структура
    1. ClientId – код клиента платежной системы, целое. Данный код выдается при подключении к платежной системе.
    2. Operation – тип операции, целое. Подробнее каждый тип операции будет рассмотрен ниже.
    3. Data – данные для выполнения операции, объект в JSON-формате.
  4. Sign – электронно-цифровая подпись, строка base64.

Библиотека для формирования запросов к системе

Для упрощения доступа к системе разработана специальная библиотека классов. Исходный код библиотеки на языке C# приведен в приложении к данному описанию.

Библиотека состоит из следующих основных классов.

Классы общего назначения:

  • AbonentPaysystemRequest – запрос к платежной системе;
  • AbonentPaysystemResponse – ответ от платежной системы;
  • ExchangeResult – результат выполнения операции;
  • RequestSignedData – входные данные для запроса;
  • ResponseSignedData – выходные данные;
  • RSASignHelper – класс, позволяющий подписывать данные с помощью сертификата.

Классы для проведения платежей:

  • Pay – платеж;
  • Enlistment – зачисление.

Классы для получения информации по абоненту:

  • Abonent – абонент;
  • AbonentAccount – сведения о лицевом счете абонента, с привязкой к поставщику услуг;
  • AbonentBalance – информация по услуге (долги, показания счетчика и т.д.).

Классы для получения списка услуг:

  • PaymentDestination – услуга.

Подпись данных с помощью библиотеки

Пример исходного кода для подписи строки: 

// Открываем файл сертификата
var cert = new X509Certificate2(Path, Password);
// Создаем класс для выполнения подписи
var signHelper = new RSASignHelper(cert);
// Выполняем подпись с помощью класса-помощника
var Sign = Convert.ToBase64String(signHelper.GetSign(Data));

Отправка запроса и получение результата

Пример исходного кода: 

requestData – объект, содержащий исходные данные для выполнения запроса к системе;
response – результат, который возвращает система.

 // Отправляем запрос
 WebRequest webRequest = WebRequest.Create(url.Text);
 webRequest.Method = "POST";
 webRequest.Timeout = 100000;
 webRequest.ContentType = "application/json";
 var sentData = Encoding.UTF8.GetBytes(requestData.ToJson());
 webRequest.ContentLength = sentData.Length;
 var sendStream = webRequest.GetRequestStream();
 sendStream.Write(sentData, 0, sentData.Length);
 sendStream.Close();
 WebResponse res = webRequest.GetResponse();
 // Получаем результаты
 var ReceiveStream = res.GetResponseStream();
 var sr = new StreamReader(ReceiveStream, Encoding.UTF8);
 var response = AbonentPaysystemResponse.FromJson(sr.ReadToEnd());


Запрос на проверку доступности платежной системы

Для проверки доступности платежной системы необходимо отправить запрос с Operation = 0 и с пустым полем Data на адрес платежной системы. В данном примере приведены все операции – от формирования запроса, до его подписи и отправки в систему. Пример исходного кода: 

 // Создаем запрос 
 var request = new AbonentPaysystemRequest()
           {
               SignedData = new RequestSignedData()
               {
                   ClientId = 1,
                   Operation = OperationType.Check,
               },
               ProtocolVersion = "v.1.0.0",
               Sign = "",
           };
// Подписываем
var cert = new X509Certificate2(Path, Password);
var signHelper = new RSASignHelper(cert);
requestData.Sign = Convert.ToBase64String(signHelper.GetSign(requestData.SignedData.ToJson()));
// Отправляем запрос
WebRequest webRequest = WebRequest.Create(url.Text);
webRequest.Method = "POST";
webRequest.Timeout = 100000;
webRequest.ContentType = "application/json";
var sentData = Encoding.UTF8.GetBytes(requestData.ToJson());
webRequest.ContentLength = sentData.Length;
var sendStream = webRequest.GetRequestStream();
sendStream.Write(sentData, 0, sentData.Length);
sendStream.Close();
WebResponse res = webRequest.GetResponse();
// Получаем результаты
var ReceiveStream = res.GetResponseStream();
var sr = new StreamReader(ReceiveStream, Encoding.UTF8);
var response = AbonentPaysystemResponse.FromJson(sr.ReadToEnd());

Запрос на получение списка услуг

Пример исходного кода: 

// Создаем запрос 
var request = new AbonentPaysystemRequest()
           {
               SignedData = new RequestSignedData()
               {
                   ClientId = 1,
                   Operation = OperationType.GetPaymentDestinations,
               },
               ProtocolVersion = "v.1.0.0",
               Sign = "",
           };
// Подписываем
…………
// Отправляем запрос
…………
// Получаем результаты
var response = AbonentPaysystemResponse.FromJson(sr.ReadToEnd());
// Отображаем результаты
var paymentDestinations = PaymentDestinations.FromJson(response.SignedData.Data);

Запрос на получение информации по лицевому счету

Пример исходного кода: 

// Создаем запрос 
var request = new AbonentPaysystemRequest()
           {
               SignedData = new RequestSignedData()
               {
                   ClientId = 1,
                   Operation = OperationType.GetAccountInfo,
               },
               ProtocolVersion = "v.1.0.0",
               Sign = "",
           };
// Формируем лицевой счет для запроса
var account = new AbonentAccount()
           {
               Account = “00000000”,
               SupplierId = 1,
           };
// Передаем лицевой счет в запрос
           request.SignedData.Data = account.ToJson();

           //Подписываем
           …………
           //Отправляем запрос
           …………
           //Получаем результаты
           var response = AbonentPaysystemResponse.FromJson(sr.ReadToEnd());
           //Отображаем результаты
           var paymentDestinations = PaymentDestinations.FromJson(response.SignedData.Data);

Запрос на проведение платежа

Пример исходного кода: 

// Создаем запрос 
var request = new AbonentPaysystemRequest()
           {
               SignedData = new RequestSignedData()
               {
                   ClientId = 1,
                   Operation = OperationType.GetAccountInfo,
               },
               ProtocolVersion = "v.1.0.0",
               Sign = "",
           };
// Формируем платеж
var pay = new Pay
           {
               Enlistments = new List<Enlistment>(),
               Id = Guid.NewGuid(),
           };
pay.PayDateTime = DateTime.Now;
pay.Enlistments.Add(new Enlistment()
           {
               Account = PayAccount.Text,
               PaymentDestinationId = 1,
               PAmmount = 0,
               CAmmount = 0,
               Id = Guid.NewGuid(),
           });
// Передаем платеж в запрос
request.SignedData.Data = pay.ToJson();
// Подписываем
…………
// Отправляем запрос
…………
// Получаем результаты
var response = AbonentPaysystemResponse.FromJson(sr.ReadToEnd());

Запрос на проверку статуса платежа

Пример исходного кода: 

// Создаем запрос 
var request = new AbonentPaysystemRequest()
           {
               SignedData = new RequestSignedData()
               {
                   ClientId = 1,
                   Operation = OperationType.GetAccountInfo,
               },
               ProtocolVersion = "v.1.0.0",
               Sign = "",
           };
// Передаем ID платежа в запрос
request.SignedData.Data = Id;
//Подписываем
…………
//Отправляем запрос
…………
//Получаем результаты
var response = AbonentPaysystemResponse.FromJson(sr.ReadToEnd());
Источник — «https://doc.abonent.plus/index.php?title=Протокол_взаимодействия_с_платежной_системой&oldid=474»