**Форматы обмена сообщениями.** **ИНТЕРФЕЙС ПОДКЛЮЧЕНИЯ (API) ДЛЯ «Агента»**
**Протокол обмена информации** **Требования к интерфейсу «АГЕНТА»**
1. Интерфейс Агента должен отправлять запросы платежной организации по протоколу - HTTPS, с IP адресов, которые были предварительно переданы техническим сотрудникам агента.
1. Интерфейс Агента должен отправлять запросы, передаваемые системой методом - POST.
1. Интерфейс Платежной организации должен формировать ответ системы в формате - JSON в кодировке - UTF-8 (если ответ содержит символы национальных алфавитов).
1. Обмен информацией ведется в режиме запрос-ответ, при этом скорость ответа не должна превышать 60 секунд, в противном случае система разрывает соединение по таймауту.
1. Если предполагаемое количество платежей за услуги подключаемого оператора, ожидается достаточно интенсивным (до 10 платежей в минуту и более), желательно, чтобы интерфейс переносил много потоковую коммуникацию не менее 10-15 одновременных соединений.
**Основные принципы работы интерфейса**
1. Каждый платеж в системе Агента имеет уникальный идентификатор, который передается
Платежной организации в переменной **Transaction ID** – целое число длиной до 15 знаков. По этому идентификатору производится дальнейшая сверка взаиморасчетов и решение спорных вопросов.
2. Сумма платежа принимается от абонента, взимается комиссия за проведение платежа в системе Агента и передается Платежной организации в валюте контракта в переменной **Amount** – дробное число с точностью до сотых, в качестве разделителя используется «.» (точка). Если сумма представляет целое число, то оно все равно дополняется точкой и нулями, например – «180.00».
3. В запросе на создание платежа, система Дилера передает дату платежа (под датой платежа в системе подразумевается дата получения запроса от клиента) в переменной Request Date - дата в формате (yyyy-mm-dd hh:mm:ss). Данный параметр не предназначен для использования при проведении сверок и бухгалтерских взаиморасчетов. При проведении сверок оборотов и бухгалтерских взаиморасчетов, Отчетный период выбирается на основании времени регистрации транзакции в системе Платежной организации по времени г.Алматы (по часовому поясу GMT+6).
6. В случае, если любой из запросов оператору завершается ошибкой, то оператор возвращает код ошибки в соответствие с таблицей, приведенной ниже. Все ошибки имеют признак фатальности. Фатальная ошибка означает для системы, что повторная отправка запроса с теми же параметрами, приведет к 100% повторению той же ошибки – следовательно система прекращает обработку клиентского запроса и завершает его с ошибкой. Не фатальная ошибка – означает, что повторение запроса с неизменными параметрами через некоторый промежуток времени, должно привести к финальному статусу запроса. Система будет повторять запросы, завершающиеся не фатальной ошибкой, постоянно увеличивая интервал, пока операция не завершится успехом или фатальной ошибкой. Если по истечении продолжительного времени запрос не принял окончательный статус – то Агенту **необходимо обратиться в техническую поддержку Платежной организации** для уточнения финального статуса запроса. Агент не в праве считать не фатальный статус запроса ошибкой, и обязуется доводить каждый запрос до финального статуса.
6. **Отсутствие связи с сервером оператора не является фатальной ошибкой. Пустая страница ответа не является фатальным статусом.** В случае возникновения подобных ситуаций – Агенту необходимо обратиться в техническую поддержку Платежной организации для устранения проблемы.
6. В базе Платежной организации не должно содержаться двух успешно проведенных платежей с одним и тем же номером **Transaction ID** от одного Агента. Если система Агента присылает повторно запрос с уже существующим в базе Платежной организации **Transaction ID**, то Платежная организация должна вернуть результат обработки предыдущего запроса.
**Порядок взаимодействия в тестовой и боевой средах**
1. В период установления деловых отношений между Сторонами, Агент и Платежная организация проводят проверку и отладку взаимодействия в рамках тестовой среды интерфейса API, который позволяет установить порядок, приема-передачи информации, тестовых платежей и иной дополнительной информации.
2. В период проведения отладки взаимодействия в рамках тестовой среды интерфейса API, стороны не несут ответственность за возможные сбои, нарушения в работе как самого интерфейса API, так и собственных интерфейсов Агента, в рамках которых осуществляется подключение к API.
3. После проведения процедуры отладки в раках тестовой среды, Агент по своему усмотрению имеет право в любое время перейти к началу приема-передачи информации, платежей и иной дополнительной информации в «боевом» режиме, т.е. режиме полной функциональной готовности Агента для работы в среде интерфейса API.
4. После начала проведения платежей в «боевом» режиме, Агент принимает на себя полную ответственность за свои действия в интерфейсе API, вызванные в том числе, но не ограничиваясь сбоями в работе систем Агента, непреднамеренной передачей данных и информации, совершение системой непреднамеренных платежей их «задвоение» в системе, ошибки в коде интерфейса API, непредвиденные отключения и блокирования действий Агента интерфейсом API, в следствие ненадлежащего подключения Агентов связанных со сбоями или нарушениями функционирования систем и интерфейсов самого Агента и др.
**ПРОТОКОЛ ОБМЕНА ИНФОРМАЦИЕЙ**
Для отправки запроса используется http протокол ContentType = "application/x-www-form-urlencoded"; Method = "POST";
**(Check) Запрос на проверку возможности проведения или создания платежа**
Этот запрос предназначен для осуществления проверки
**Пример**
```json
AgentID=\*\*&TransactionID=113&RequestDate=2017-05-21 2015:45:15&Service=1&Amount=0.50&RequestType=AccountCheck&AgentPassword=\*\*\*\* \*&account=\*\*\*\*\*\*@\*\*\*\*.\*\*\*&Currency=USD
```
Ответ
```shell
{
"RequestID":2141731,
"ResponseType":"Payment",
"TransactinID":113,
"ResponseStatus":1,
"Message":"Транзакция успешна", "TransactionContent":
{
"Service":395, "account":"\*\*\*\*\*\*\*@\*\*\*\*.\*\*\*", "Amount":0.5,
"Currency":" USD ", "ExchangeRate":62.969004894, "ServiceCurrency":"RUB", "Extras":null
}
}
```
**Запрос на проведение транзакции**
Этот запрос предназначен для осуществления платежа
**Пример**
```json
AgentID=\*\*&TransactionID=113&RequestDate=2017-05-21 2015:45:15&Service=1&Amount=0.50&RequestType=Payment&AgentPassword=\*\*\*\* \*&account=\*\*\*\*\*\*@\*\*\*\*.\*\*\*&Currency=USD
```
Ответ
```shell
{
"RequestID":2141731,
"ResponseType":"Payment",
"TransactinID":113,
"ResponseStatus":1,
"Message":"Транзакция успешна", "TransactionContent":
{
"Service":395, "account":"\*\*\*\*\*\*\*@\*\*\*\*.\*\*\*", "Amount":0.5,
"Currency":" USD ", "ExchangeRate":62.969004894, "ServiceCurrency":"RUB", "Extras":null
}
}
```
**Запрос на проверку статуса транзакции**
Этот запрос предназначен для проверки текущего статуса транзакции. Для проверки текущего статуса так же можно использовать Запрос на проведения транзакции с данными интересующего платежа
**Пример**
```json
AgentID=\*\*&TransactionID=113&RequestType=Status&AgentPassword=\*\*\*\*\*
```
Ответ
```shell
{
"RequestID":2141731,
"ResponseType":"Status",
"TransactinID":113,
"ResponseStatus":10,
"Message":"Транзакция успешна", "TransactionContent":
{
"Service":395, "account":"\*\*\*\*\*\*\*@\*\*\*\*.\*\*\*", "Amount":0.5, "Currency":"USD", "ExchangeRate":62.969004894, "ServiceCurrency":"RUB", "Extras":null
}
}
```
**Запрос Баланса**
Этот запрос предназначен для получения текущего баланса в системе Платежной организации
**Пример**
```json
AgentID=\*\*&RequestType=CheckBalance&AgentPassword=\*\*\*\*\*
```
Ответ
```shell
{
"AgentID":1, "ResponseType":"CheckBalance", "Balances":
[
{ "Balance":-11.1,
"Overbalance":100.0, "Currency":"USD" },
{ "Balance":1310.7796, "Overbalance":1000.0, "Currency":"RUB"},
{ "Balance":-24397.213, "Overbalance":100000.0, "Currency":"KZT" }
]
}
```
При чек запросе по таким сервисам, где требуется провести платеж на определенную сумму, вы будите получать в Extras дополнительный параметр OrderAmount в которой будет указано на какую сумму необходимо провести платеж в валюте заключенного договора, обычно используется для гифт карт и Яндекс кассы.
Получив такой параметр, вы будите знать, что для успешного проведения платежа необходимо именно на эту сумму сделать платеж. Мы от поставщиков в свою очередь тоже получаем такой параметр и транслируем вам с конвертацией в валюту заключенного договора.
Но нужно учесть, что при конвертации в валюту заключенного договора сумма за гифты будет зависеть от курсов банка, поэтому сумма может плавать в зависимости от банковских курсов, и необходимо, перед проведением платежа, произвести чек запрос, при котором в ответе вы получите реальную стоимость в валюте договора.
|AgentID |Идентификационный номер Агента |Int |
| :- | :- | :- |
|ResponseType |Типа запроса |String |
|Balances |Представление массива по имеющегося баланса в разных разным валютам |Money |
|Currency |Валюта |String |
|Balance |Текущий баланс |Money |
|Overbalance |Текущий овердрафт |Money |
**Статусы** **Список кодов ответа системы оператора**
|ResponseStatus |Message |Final |
| - | - | - |
|1 |Транзакция создана |- |
|2 |Транзакция в процессе отправки к поставщику |- |
|3 |Транзакция создана у поставщика |- |
|4 |Запрос обрабатывается |- |
|5 |Запрос обрабатывается |- |
|9 |Транзакция в процессе получения статуса |- |
|10 |Транзакция успешна |+ |
|-1 |Ошибка авторизации |+ |
|-2 |Недостаточно средств для транзакции |+ |
|-3 |Транзакция отменена |+ |
|-4 |Транзакция не найдена |+ |
|-100 |Неверный формат аккаунта по услуге|+ |
|-105 |Аккаунт не найден |+ |
|-110 |Транзакция невозможна по запрету оператора |+ |
|-115 |Транзакция невозможна по техническим причинам |+ |
|-120 |Аккаунт неактивен |+ |
|-200 |Сумма в недопустимом диапазоне |+ |
|-201 |Сумма мала |+ |
|-202 |Сумма велика |+ |
|-203 |Не удалось проверить счет |+ |
|-300 |Неизвестная ошибка оператора |+ |
|-500 |Ошибка запроса |+ |
|-501 |Сервисный маршрут не найден |+ |
|-502 |Обменный курс не найден |+ |
|-503 |Ошибка при записи платежа в БД |-
