Протокол взаимодействия с платежной системой
В данном документе описан регламент технического взаимодействия платежной системы «Абонент» с программным обеспечением агента по приему платежей по протоколу HTTP(S).
Документ предназначен для разработчиков программного обеспечения работающего на стороне агентов по приему платежей.
Содержание
Термины и определения
Система – платежная система «Абонент».
Агент – организация, осуществляющая прием оплаты через платежную систему «Абонент».
Алгоритм взаимодействия с системой
Взаимодействие с системой осуществляется в режиме запрос – ответ. Инициатором связи является клиентское ПО агента.
Для начала взаимодействия с системой агентом должны быть получены сертификат цифровой подписи и код клиента по приему платежей. Эти данные выдаются при подключении к системе. Запрещается передача этих сведений третьим лицам.
Общее описание допустимых запросов к системе
В функционал программного обеспечения работающего на стороне агента по приему платежей входит:
- Возможность выполнения запроса проверки доступности системы.
- Возможность получения списка доступных услуг.
- Возможность получения информации по лицевому счету для проведения платежа.
- Возможность проведения оплаты по указанному лицевому счету и по указанной услуге.
На каждый запрос система возвращает результат выполнения запроса и описание результата выполнения. В случае ошибки, система вернет также расширенное описание ошибки.
Допустимы следующие результаты выполнения операций:
- 0 – запрос успешно обработан;
- -1 – некорректная подпись;
- -2 – версия протокола не поддерживается;
- -3 – произошла ошибка обработки запроса.
Кроме того, по определенным типам запросов система может возвращать выходные параметры.
Набор входных и выходных параметров по каждому типу запроса описан в следующих разделах.
1. Проверить соединение
- Входные параметры – код клиента.
- Выходные параметры – отсутствуют.
2. Получить список услуг
- Входные параметры – код клиента.
- Выходные параметры:
- Код услуги или ресурса (в дальнейшем используется для формирования платежа).
- Наименование услуги или ресурса.
- Код организации, оказывающей услугу или поставляющей ресурс.
- Наименование организации, оказывающей услугу или поставляющей ресурс.
- Код типа лицевого счета, используемый для идентификации плательщика.
- Наименование типа лицевого счета, используемого для идентификации плательщика.
- Реквизиты организации для перечисления средств.
- Дополнительные поля для формирования платежа.
3. Получить данные по абоненту
- Входные параметры:
- Код типа лицевого счета.
- Лицевой счет.
- Выходные параметры:
- Код типа лицевого счета.
- Лицевой счет абонента.
- Список альтернативных лицевых счетов абонента с указанием типа.
- Список услуг абонента с информацией для приема платежа (текущая задолженность, признак наличия счетчика, последние показания счетчика и дата их съема, текущий тариф).
4. Зарегистрировать платеж
- Входные параметры:
- Уникальный номер платежа (Guid).
- Дата/время.
- Примечание.
- Другая информация.
- Зачисления - список сумм оплат, с разбивкой по услугам, с указанием для каждой услуги:
- Кода типа лицевого счета.
- Лицевого счета.
- Кода услуги.
- Суммы платежа.
- Дополнительные параметры (текущие показания счетчика, оплачиваемы объем и т.д.).
- Выходные параметры – результат обработки (поставлен в очередь, отклонен и т.д.)
5. Проверить статус платежа
- Входные параметры – уникальный номер платежа (Guid).
- Выходные параметры: список зачислений с указанием результатов обработки по каждому из зачислений (отправлено поставщику услуг/находится в очереди на обработку/ошибка и т.д.).
Общая структура взаимодействия
Инициатором обмена является ПО агента по приему платежей. Запросы посылаются через интернет, по протоколу HTTP(S) методом POST. Данные передаются в JSON-формате. Каждый запрос обязательно должен быть подписан с помощью ЭЦП агента.
Запрос должен содержать следующие поля:
- ProtocolVersion – версия протокола, строка.
- DataFormat- формат данных в поле Data. В настоящее время поддерживается только формат JSON, что соответствует значению 0 в данном поле.
- SignedData – подписываемые данные, структура
- ClientId – код клиента платежной системы, целое. Данный код выдается при подключении к платежной системе.
- Operation – тип операции, целое. Подробнее каждый тип операции будет рассмотрен ниже.
- Data – данные для выполнения операции, объект в JSON-формате.
- 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)); 3. Отправка запроса и получение результата Пример исходного кода: 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());
4. Запрос на проверку доступности платежной системы Для проверки доступности платежной системы необходимо отправить запрос с 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());
5. Запрос на получение списка услуг Пример исходного кода: //Создаем запрос 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);
6. Запрос на получение информации по лицевому счету Пример исходного кода: //Создаем запрос 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);
7. Запрос на проведение платежа Пример исходного кода: //Создаем запрос 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());
8. Запрос на проверку статуса платежа Пример исходного кода: //Создаем запрос 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());
