Форматы обмена сообщениями. Интерфейс подключения (API) для «Агента»

Протокол обмена информации. Требования к интерфейсу «АГЕНТА»

1. Интерфейс Агента должен отправлять запросы платежной организации по протоколу - HTTPS, с IP адресов, которые были предварительно переданы техническим сотрудникам агента.
2. Интерфейс Агента должен отправлять запросы, передаваемые системой методом - POST.
3. Интерфейс Платежной организации должен формировать ответ системы в формате - JSON в кодировке - UTF-8 (если ответ содержит символы национальных алфавитов).
4. Обмен информацией ведется в режиме запрос-ответ, при этом скорость ответа не должна превышать 60 секунд, в противном случае система разрывает соединение по таймауту.
5. Если предполагаемое количество платежей за услуги подключаемого оператора, ожидается достаточно интенсивным (до 10 платежей в минуту и более), желательно, чтобы интерфейс переносил много потоковую коммуникацию не менее 10-15 одновременных соединений.

Основные принципы работы интерфейса

1. Каждый платеж в системе Агента имеет уникальный идентификатор, который передается Платежной организации в переменной Transaction ID – целое число длиной до 15 знаков. По этому идентификатору производится дальнейшая сверка взаиморасчетов и решение спорных вопросов.
2. Сумма платежа принимается от абонента, взимается комиссия за проведение платежа в системе Агента и передается Платежной организации в валюте контракта в переменной Amount – дробное число с точностью до сотых, в качестве разделителя используется «.» (точка). Если сумма представляет целое число, то оно все равно дополняется точкой и нулями, например – «180.00».
3. В запросе на создание платежа, система Дилера передает дату платежа (под датой платежа в системе подразумевается дата получения запроса от клиента) в переменной Request Date - дата в формате (yyyy-mm-dd hh:mm:ss). Данный параметр не предназначен для использования при проведении сверок и бухгалтерских взаиморасчетов. При проведении сверок оборотов и бухгалтерских взаиморасчетов, Отчетный период выбирается на основании времени регистрации транзакции в системе Платежной организации по времени г. Алматы (по часовому поясу GMT+6).
4. В случае, если любой из запросов оператору завершается ошибкой, то оператор возвращает код ошибки в соответствие с таблицей, приведенной ниже. Все ошибки имеют признак фатальности. Фатальная ошибка означает для системы, что повторная отправка запроса с теми же параметрами, приведет к 100% повторению той же ошибки – следовательно система прекращает обработку клиентского запроса и завершает его с ошибкой. Не фатальная ошибка – означает, что повторение запроса с неизменными параметрами через некоторый промежуток времени, должно привести к финальному статусу запроса. Система будет повторять запросы, завершающиеся не фатальной ошибкой, постоянно увеличивая интервал, пока операция не завершится успехом или фатальной ошибкой. Если по истечении продолжительного времени запрос не принял окончательный статус – то Агенту необходимо обратиться в техническую поддержку Платежной организации для уточнения финального статуса запроса. Агент не в праве считать не фатальный статус запроса ошибкой, и обязуется доводить каждый запрос до финального статуса.
5. Отсутствие связи с сервером оператора не является фатальной ошибкой. Пустая страница ответа не является фатальным статусом. В случае возникновения подобных ситуаций – Агенту необходимо обратиться в техническую поддержку Платежной организации для устранения проблемы.
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) Запрос на проверку возможности проведения или создания платежа

Этот запрос предназначен для осуществления проверки

Пример запроса:

AgentID=\*\*&TransactionID=113&RequestDate=2017-05-21 2015:45:15&Service=1&Amount=0.50&RequestType=AccountCheck&AgentPassword=\*\*\*\* \*&account=\*\*\*\*\*\*@\*\*\*\*.\*\*\*&Currency=USD

Ответ:

{ 
"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 
} 
}

Запрос на проведение транзакции

Этот запрос предназначен для осуществления платежа

Пример запроса:

AgentID=\*\*&TransactionID=113&RequestDate=2017-05-21 2015:45:15&Service=1&Amount=0.50&RequestType=AccountCheck&AgentPassword=\*\*\*\* \*&account=\*\*\*\*\*\*@\*\*\*\*.\*\*\*&Currency=USD 

Ответ:

{ 
"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 
} 
}

Запрос на проверку статуса транзакции

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

Пример запроса:

AgentID=\*\*&TransactionID=113&RequestType=Status&AgentPassword=\*\*\*\*\* 

Ответ:

{ 
"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 
} 
} 

Запрос Баланса

Этот запрос предназначен для получения текущего баланса в системе Платежной организации

Пример запроса:

AgentID=\*\*&RequestType=CheckBalance&AgentPassword=\*\*\*\*\* 

Ответ:

{ 
"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 в которой будет указано на какую сумму необходимо провести платеж в валюте заключенного договора, обычно используется для гифт карт и Яндекс кассы.

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

Но нужно учесть, что при конвертации в валюту заключенного договора сумма за гифты будет зависеть от курсов банка, поэтому сумма может плавать в зависимости от банковских курсов, и необходимо, перед проведением платежа, произвести чек запрос, при котором в ответе вы получите реальную стоимость в валюте договора.

Статусы. Список кодов ответа системы оператора

На этой странице

• Форматы обмена сообщениями. Интерфейс подключения (API) для «Агента»
• Основные принципы работы интерфейса
• Порядок взаимодействия в тестовой и боевой средах
• Протокол обмена информацией
• (Check) Запрос на проверку возможности проведения или создания платежа
• Запрос на проведение транзакции
• Запрос на проверку статуса транзакции
• Запрос Баланса
• Статусы. Список кодов ответа системы оператора