Протокол взаимодействия информационной системы агента с процессинговым
центром
Оглавление
1. Общие сведения …………………………………………………………………………………………………………………. 2
2. 1.1 Назначение документа …………………………………………………………………………………………………… 2
1.2 Формат передачи данных ……………………………………………………………………………………………….. 2
1.3 Авторизация …………………………………………………………………………………………………………………… 2
1.4 Общее описание и принципы взаимодействия ……………………………………………………………….. 2
1.5 Формат запроса и ответа ………………………………………………………………………………………………… 3
Примеры запросов и ответов ………………………………………………………………………………………………. 4
2.1 Проверка возможности проведения платежа (check) ………………………………………………………. 4
2.2 Проведение платежа (pay) ……………………………………………………………………………………………… 7
2.3 Получение информации по доступным сервисам (getServices) …………………………………………. 9
2.4 Получение информацию по определенному сервису (getService) …………………………………… 11
2.5 Получить информацию о доступном балансе агента (getBalance) …………………………………… 13
3. Справочники …………………………………………………………………………………………………………………….. 14
3.1 Список кодов ответа на запросы ……………………………………………………………………………………. 14
3.2 Типы схем по которой работает услуга ………………………………………………………………………….. 141. Общие сведения
1.1 Назначение документа
Данный документ описывает взаимодействие информационной системы (далее ИС) агента с
процессинговым центром (далее ПЦ) по приему платежей.
В рамках протокола возможны не только операции по зачислению средств по услугам, но и
операции по получению данных по сервисам, получение баланса агента.
Процесс взаимодействия позволяет:
1. 3. 4. 5. Проверять возможность проверки проведения платежа (check).
2. Проводить платежи (pay)
Получить информацию по доступным сервисам (getServices)
Получить информацию по определенному сервису (getService)
Получить информацию о доступном балансе агента (getBalance)
1.2 Формат передачи данных
Взаимодействие между ИС Агента и ПЦ осуществляется по протоколу HTTPS. URL-адрес тестового и
продуктового ПЦ предоставляется Агенту отдельным письмом.
Все запросы к ПЦ передаются методом POST в формат JSON (Content-Type: application/json, Accept:
application/json) в кодировке UTF-8. По результатам обработки полученного сообщения ПЦ
возвращает ответ в том же формате: JSON (Content-Type: application/json) в кодировке UTF-8
1.3 Авторизация
Авторизация запросов от ИС Агента в ПЦ осуществляется с использованием токенов и IP-адресов.
Управление параметрами авторизации осуществляется через личный кабинет Агента в разделе
«Настройки авторизации».
Для создания токена необходимо кликнуть «Создать новый Token» и подтвердите свое действие.
Созданный токен будет автоматически отправлен на сервер ПЦ для подтверждения регистрации
(для токена будет выставлен статус «Ожидайте подтверждения»). Токены, успешно
подтвержденные оператором ПЦ, переводятся в статус «Токен подтвержден». Для отзыва
действующего токена необходимо кликнуть «Удалить», токен будет переведен в статус «Токен
отозван». Токен ИС Агента передается в заголовке запроса Authorization: «Bearer »+{Token}).
При необходимости, взаимодействие с ПЦ может быть ограничено набором IP-адресов, с которых
будут приниматься запросы. Для ввода ограничения по IP-адресу необходимо щелкнуть «Создать
новый IP-адрес» и указать IP для которого будет введено разрешение на прием запросов ПЦ.
1.4 Общее описание и принципы взаимодействия
Каждый платеж в системе Агента имеет уникальный идентификатор, который передается в ПЦ в
переменной agentPaymentId – целое число длиной до 18 знаков. По данному идентификатору
производится дальнейшая сверка взаиморасчетов и решение спорных вопросов.
На каждый переданный в ПЦ платеж возвращается уникальный номер транзакции проведения
платежа в переменной paymentId – целое число длиной до 18 знаков. По значению paymentId так
же можно провести сверку взаиморасчетов и решения спорных вопросов.
При проведении платежа сумма к зачислению передается в переменной sumTo – дробное число с
точностью до сотых, в качестве разделителя используется «.» (точка). Если сумма представляет
целое число, то оно дополняется точкой и нулями, например – «180.00».
При проведении платежа сумма, принятая от клиента, передается в переменной sumFrom –
дробное число с точностью до сотых, в качестве разделителя используется «.» (точка). Если сумма
представляет целое число, то оно дополняется точкой и нулями, например – «200.00».В запросе на проведение платежа pay, Агент передает дату платежа (под датой платежа
подразумевается дата получения запроса от клиента) в переменной agentPaymentDate – дата в
формате YYYY-MM-DDThh:mm:ss.
Идентификатор пользователя (плательщика) (номер лицевого счета, телефона, логин и т.д.)
передается в переменной account – строка, содержащая буквы, цифры и спецсимволы, длиной до
200 символов. Перед отправкой запроса в ПЦ, ИС Агента должен произвести проверку корректности
в соответствии с регулярным выражением, которое можно получить в ответе на запрос списка
доступных сервисов getServices.
При проведении платежей в пользу некоторых сервисов возможна передача дополнительных
полей (дополнительные данные, введенные пользователем (плательщиком), номер терминала,
тип платежа и т.п.) которые передаются в ПЦ как дополнительные поля в объекте additionalParams,
при платеже может быть передано одно или несколько дополнительных полей в зависимости от
требований провайдера услуг. Например, при оплате заказа пользователь вводит свой логин и
номер заказа, в таком случае логин передается в параметре account, а номер заказа в
дополнительном поле orderId. Список параметров необходимых при проведении платежа можно
получить путем отправки запроса на получение списка доступных сервисов getServices.
Проведение платежа производится в 2 этапа – проверка возможности проведения платежа check,
а также проверка идентификатора клиента и непосредственно проведение платежа pay. Тип
запроса передается как часть пути до сервиса.
Если у Агента имеется техническая возможность идентифицировать плательщиков — то
идентификационные данные плательщика указываются в параметре documentNumber и
personName.
Результат выполнения запроса возвращается ПЦ в виде кодов ответов в параметре resultCode, все
возможные коды ответа можно посмотреть в Таблице 1 «Список кодов ответа на запросы». Все
коды ответов кроме 0 имеют признак финальности «+/-». Финальный код ответа (тот что отмечен
символом «+») означает, что повторная отправка запроса с теми же параметрами, приведет к 100%
возврату такого же кода ответа – следовательно, при получении финального кода ответа сервис
Агента прекращает отправку запроса и присваивает платежу статус в зависимости от кода ответа.
Нефинальный (временный) код ответа означает, что сервис Агента должен повторять запросы,
постоянно увеличивая интервал, пока не получит код ответа 0 или финальный код ответа.
Отсутствие связи с ПЦ является нефинальной ошибкой.
В ПЦ не должно содержаться двух успешно проведенных платежей от одного Агента с одним и тем
же номером транзакции agentPaymentId. Если сервис Агента повторно присылает запрос на
проведение платежа с уже существующим в ПЦ agentPaymentId, то ПЦ возвращает результат
обработки предыдущего запроса.
Идентификатор сервиса передается в параметре serviceCode, список доступных для агента
сервисов, их описание, входные параметры и возвращаемые значения можно получить путем
отправки запроса getServices
1.5 Формат запроса и ответа
В общем виде запрос выглядит следующим образом:{
«serviceCode«: «{serviceCode}»,
«account«: «{account}«,
«agentPaymentId«: {agentPaymentId},
«agentPaymentDate«: «{agentPaymentDate}»,
«sumTo«: {sumTo},
«sumFrom«: {sumFrom}
}
В общем виде ответ выглядит следующим образом:
{
«resultCode«: {resultCode},
«message«: «{message}«,
«paymentId«: {paymentId},
«agentPaymentId«: {agentPaymentId}
}
2. Примеры запросов и ответов
2.1 Проверка возможности проведения платежа (check)
Структура запроса
Метод | POST |
URI | <адрес ПЦ>/api/v30/check |
URI Parameters | без параметров |
Body Parameters | параметры запроса |
Content-Type | application/json |
Стандартный запрос
Параметры запроса | ||
параметр | описание | обязательный |
serviceCode | код услуги в ПЦ | да |
account | идентификатор пользователя (номер телефона, email и т.п.) | да |
agentPaymentId | идентификатор операции на стороне Агента | да |
agentPaymentDate | дата операции на стороне Агента | да |
sumTo | сумма платежа. Сумма к зачислению | да |
sumFrom | сумма принятая от пользователя | да |
ПРИМЕЧАНИЕ В запросе check значение в параметрах sumTo и sumFrom может передаваться минимальная сумма платежа по сервису. | ||
Пример запроса
application/json, text/json
{
«serviceCode»: «P1011»,
«account»: «7770017711»,
«agentPaymentId»: 1233355,
«agentPaymentDate»: «2015-02-17T16:48:37»,
«sumTo»: 200.00,
«sumFrom»: 200.00
}Запрос с идентификационными данными пользователя
Параметры запроса
параметр | описание | |
serviceCode | код услуги в ПЦ | |
account | идентификатор пользователя (номер телефона, email и т.п.) | |
agentPaymentId | идентификатор операции на стороне Агента | |
agentPaymentDate | дата операции на стороне Агента | |
sumTo | сумма платежа. Сумма к зачислению | |
sumFrom | сумма принятая от пользователя | |
documentNumber | номер паспорта или удостоверения личности пользователя | |
personName | ФИО пользователя | |
ПРИМЕЧАНИЕ | Согласно закону о платежах и платежных системах законодательством некоторых стран при оплате услуг пользователь должен передавать свои идентификационные данные такие как номер паспорта и ФИО. | |
Пример запроса
application/json, text/json
{
«serviceCode»: «P1011»,
«account»: «7770017711»,
«agentPaymentId»: 1233355,
«agentPaymentDate»: «2015-02-17T16:48:37»,
«sumTo»: 200.00,
«sumFrom»: 200.00,
«documentNumber»: «123456789»,
«personName»: «Иванов Иван Иванович»
}
Запрос с проверкой номера и дополнительными полями
Параметры запроса
параметр описание обязательный
serviceCode код услуги в ПЦ да
account идентификатор пользователя (номер телефона, email и т.п.) да
agentPaymentId идентификатор операции на стороне Агента да
agentPaymentDate дата операции на стороне Агента да
sumTo сумма платежа. Сумма к зачислению нет
sumFrom сумма принятая от пользователя нет
additionalParams тег-контейнер для дополнительных полей да
email дополнительное поле email нет
account2 дополнительное поле account2 нет
ПРИМЕЧАНИЕ При check запросе по некоторым услугам необходима передача дополнительных
полей это могут быть дополнительные данные, введенные пользователем
(плательщиком), тип платежа, номер заказа, номер брони и т.п. которые
передаются агентом как дополнительные поля в объекте additionalParams.
Например, при оплате услуги, пользователь помимо основного идентификатора
должен ввести дополнительные данные такие как email и номер заказа.Пример запроса
application/json, text/json
{
«serviceCode»: «P1012»,
«account»: «0»,
«agentPaymentId»: 1233355,
«agentPaymentDate»: «2015-02-17T16:48:37»,
«sumTo»: 200.00,
«sumFrom»: 200.00,
«additionalParams»: {
«email»: «test@gmail.com»,
«account2»: «121231»
}
}
Ответ с результатом проверки платежа и проверки номера
Параметры ответа
параметр | описание | обязательный |
resultCode | код ответа на запрос | да |
message | описание ошибки если resultCode !=0 | да |
paymentId | номер транзакции в ПЦ | да |
agentPaymentId | идентификатор операции на стороне Агента | да |
Пример ответа
application/json, text/json
{
«resultCode»: 0,
«message»: «ok»,
«paymentId»: 100000781233355,
«agentPaymentId»: 1233355
}
Ответ с результатом проверки платежа и проверки номера по международным услугам
Структура ответа
параметр | описание | обязательный |
resultCode | код ответа на запрос | да |
message | описание ошибки если resultCode !=0 | да |
paymentId | номер транзакции в ПЦ | да |
agentPaymentId | идентификатор операции на стороне Агента | да |
currencyRate | сообщение о курсе конвертации для пользователя (если resultCode = 0) | нет |
rate | курс конвертации (если resultCode = 0) | нет |
finalSum | сумма которая поступит пользователю в валюте провайдера (если resultCode = 0) | нет |
currency | валюта провайдера (если resultCode = 0) | нет |
Пример ответа
application/json, text/json{
«resultCode»: 0,
«message»: «Успешно»
,
«paymentId»: 1402546,
«agentPaymentId»: 12,
«currencyRate»: «Курс конвертации KZT/USD 0.0021»,
«rate»: 0.0020833333,
«finalSum»: 1.75,
«currency»: «USD»
}
Ответ с данными для вывода пользователю
Структура ответа
параметр описание обязательный
resultCode код ответа на запрос да
message описание ошибки если resultCode !=0 да
paymentId номер транзакции в ПЦ да
agentPaymentId номер транзакции Агента да
interfaceData объект/тег-контейнер для перечня выводимых пользователю
данных
нет
ПРИМЕЧАНИЕ В объекте interfaceData может вернутся от 1 до 30 параметров значение которых
необходимо вывести пользователю или использовать при платеже, посмотреть какие
параметры возвращаются по услуге можно с помощью запроса на получение списка
доступных услуг (getServices)
Пример ответа
application/json, text/json
{
«resultCode»: 0,
«message»: «ok»,
«paymentId»: 270,
«agentPaymentId»: 205,
«interfaceData»: {
«fio»: «Test fio»,
«address»: «Набережная 134 кв 5»,
«info»: «Сумма к оплате 20000.00 тенге»
}
}
2.2 Проведение платежа (pay)
Структура запроса
Метод POST
URI <адрес ПЦ>/api/v30/pay
URI Parameters без параметров
Body Parameters параметры запроса
Content-Type application/json
Стандартный запрос
Параметры запросапараметр описание обязательный
serviceCode код услуги в ПЦ да
account идентификатор пользователя (номер телефона, email и т.п.) да
agentPaymentId идентификатор операции на стороне Агента да
agentPaymentDate дата операции на стороне Агента да
sumTo сумма платежа. Сумма к зачислению да
sumFrom сумма принятая от пользователя нет
ПРИМЕЧАНИЕ В запросе pay сумма платежа sumTo и сумма принятая от пользователя
sumFrom — дробное число с точностью до сотых, в качестве разделителя
используется «.» (точка). Если сумма представляет целое число, то оно
дополняется точкой и нулями, например – «200.00».
Пример запроса
application/json, text/json
{
«serviceCode»: «P1011»,
«account»: «7770017711»,
«agentPaymentId»: 1233355,
«agentPaymentDate»: «2015-02-17T16:48:37»,
«sumTo»: 200.00,
«sumFrom»: 200.00
}
Запрос на проведения платежа с дополнительными полями
Параметры запроса
параметр описание обязательный
serviceCode код услуги в ПЦ да
account идентификатор пользователя (номер телефона, email и т.п.) да
agentPaymentId идентификатор операции на стороне Агента да
agentPaymentDate дата операции на стороне Агента да
sumTo сумма платежа. Сумма к зачислению да
sumFrom сумма принятая от пользователя да
additionalParams тег-контейнер для дополнительных полей нет
account1 дополнительное поле account1 нет
account2 дополнительное поле account2 нет
Пример запроса
application/json, text/json
{
«serviceCode»: «P1011»,
«account»: «7770017711»,
«agentPaymentId»: 1233355,
«agentPaymentDate»: «2015-02-17T16:48:37»,
«sumTo»: 200.00,
«sumFrom»: 200.00,
«additionalParams»: {
«account1»: «test@gmail.com»,
«account2»: «121231»
}}
Ответ на проведение платежа
Параметры ответа
параметр описание обязательный
resultCode код ответа на запрос да
message описание ошибки если resultCode !=0 да
paymentId номер транзакции в ПЦ да
agentPaymentId идентификатор операции на стороне Агента да
paymentDate дата и время платежа в ПЦ нет
paymentStatusDate дата и время, когда платеж принял окончательный статус ПРИМЕЧАНИЕ нет
В случае успешного проведения платежа в ответе возвращаются параметры
paymentDate – дата и время платежа в ПЦ и paymentStatusDate – дата и время,
когда платеж принял окончательный статус
Пример ответа
application/json, text/json
{
«resultCode»: 0,
«message»: «Успешно»,
«paymentId»: 1402779,
«paymentDate»: «2022-10-19T20:19:23.737»,
«paymentStatusDate»: «2022-10-19T20:19:24.940»,
«agentPaymentId»: 26801048196008
}
2.3 Структура запроса
Получение информации по доступным сервисам (getServices)
Метод POST
URI <адрес ПЦ>/api/v30/getServices
URI Parameters без параметров
Body Parameters без параметров
Content-Type application/json
Структура ответа
параметр описание обязательный
serviсes объект, содержащий информацию по услугам да
serviceCode код услуги в ПЦ да
type тип схемы по которой работает услуга (см. Таблица 2) да
name наименование услуги да
group группа к которой относится услуга нет
fixedPayment фиксированная сумма платежа (true – для услуг при оплате
которых необходима фиксированная сумма платежа например
оплата заказа или брони), сумма к оплате по таким сервисам
возвращается в fixedSum
нет
country страна в которой предоставляется сервис нет
inputParams объект, содержащий информацию по входящим параметрам
которые должен ввести пользователь
нет
name название параметра
required признак обязательности параметраtitle подсказка для пользователя с краткими указаниями того, что
необходимо сделать
regexp регулярное выражение для проверки вводимых данных
interfaceData объект, содержащий информацию по данным для отображения
пользователю
нет
name название параметра
required признак обязательности параметра
Пример ответа
application/json, text/json
{
«resultCode»: 0,
«message»: «OK»,
«serviсes»: [
{
«serviceCode»: «P1011»,
«type»: 0,
«name»: «Билайн Казахстан»,
«group»: «Сотовая связь»,
«fixedPayment»: true,
«country»: «КАЗАХСТАН»,
«inputParams»: [
{
«name»: «account»,
«required»: true,
«title»: «Номер телефона»,
«regexp»: «^\\d{10}$»
}
]
},{
«serviceCode»: «P1012»,
«type»: 0,
«name»: «Herbalife»
,
«group»: «Товары по каталогам»,
«fixedPayment»: true,
«country»: «КАЗАХСТАН»,
«inputParams»: [
{
«name»: «account»,
«required»: true,
«title»: «Номер независимого партнера»,
«regexp»: «^\\d{10}$»
}, {
«name»: «ev_account1»,
«required»: true,
«title»: «Номер заказа»,
«regexp»: «^\\d{10}$»
}
],
«interfaceData»: [
{«name»: «fio»,
«required»: true,
«title»: «ФИО»,
«regexp»: «^.+$»
}, {
«name»: «info»,
«required»: true,
«title»: «Сумма к оплате»,
«regexp»: «^.+$»
}, {
«name»: «fixedAmount»,
«required»: true,
«title»: «»
,
«regexp»: «^\\d{1,9}\\.\\d{2}$»
}
]
},{
«serviceCode»: «P0006»,
«type»: 2,
«name»: «XXX банк»,
«group»: «Другие услуги»,
«fixedPayment»: false,
«country»: «КАЗАХСТАН»,
«inputParams»: [
{
«name»: «account»,
«required»: true,
«title»: «Введите ИИН»,
«regexp»: «^\\d{12}$»
}
]
}
]
}
2.4 Структура запроса
Получение информацию по определенному сервису (getService)
Метод POST
URI <адрес ПЦ>/api/v30/getService
URI Parameters без параметров
Body Parameters параметры запроса
Content-Type application/json
Параметры запроса
параметр описание обязательный
serviceCode код услуги в ПЦ да
Запрос на получение информации по определенному сервису
Пример запросаapplication/json, text/json
{
«serviceCode»: «P1012»
}
Структура ответа
параметр описание serviсes объект, содержащий информацию по услугам serviceCode код услуги в ПЦ type тип схемы по которой работает услуга (см. Таблица 2) name наименование услуги group группа к которой относится услуга fixedPayment фиксированная сумма платежа (true – для услуг при оплате которых
необходима фиксированная сумма платежа например оплата
заказа или брони), сумма к оплате по таким сервисам возвращается
в fixedSum
country страна в которой предоставляется сервис inputParams объект, содержащий информацию по входящим параметрам
которые должен ввести пользователь
name название параметра
required признак обязательности параметра
title подсказка для пользователя с краткими указаниями того, что
необходимо сделать
regexp регулярное выражение для проверки вводимых данных
interfaceData объект, содержащий информацию по данным для отображения
пользователю
name название параметра
required признак обязательности параметра
Ответ на запрос информации по определенному сервису
Пример ответа
application/json, text/json
{
«resultCode»: 0,
«message»: «OK»,
«serviсes»: [
{
«serviceCode»: «P1012»,
«type»: 0,
«name»: «Herbalife»,
«group»: «Товары по каталогам»
,
«fixedPayment»: true,
«country»: «КАЗАХСТАН»,
«inputParams»: [
{
«name»: «account»,
«required»: true,
«title»: «Номер независимого партнера»,
«regexp»: «^\\d{10}$»
}, {
«name»: «ev_account1»,
обязательный
да
да
да
да
нет
нет
нет
нет
нет«required»: true,
«title»: «Номер заказа»,
«regexp»: «^\\d{10}$»
}
],
«interfaceData»: [
{
«name»: «fio»,
«required»: true,
«title»: «ФИО»,
«regexp»: «^.+$»
}, {
«name»: «info»,
«required»: true,
«title»: «Сумма к оплате»,
«regexp»: «^.+$»
}, {
«name»: «fixedAmount»,
«required»: true,
«title»: «»
,
«regexp»: «^\\d{1,9}\\.\\d{2}$»
}
]
}
]
}
2.5 Структура запроса
Получить информацию о доступном балансе агента (getBalance)
Метод POST
URI <адрес ПЦ>/api/v30/getBalance
URI Parameters без параметров
Body Parameters без параметров
Content-Type application/json
Структура ответа
параметр описание обязательный
agentId идентификатор Агента да
agentName наименование Агента да
balance баланс Агента да
overdraft сумма баланса, при достижении которого прием платежей будет
отключен автоматически
да
notification сумма баланса, при достижении которого будет отправлено
уведомление сотруднику Агента
нет
currency валюта договора нет
Пример ответа
application/json, text/json
{
«resultCode»: 0,«message»: «Успешно»,
«agent»: {
«agentId»: 4,
«agentName»: «Наименоване Агента»,
«balance»: 509455.9000,
«overdraft»: 0.0000,
«notification»: 0.0000,
«currency»: «KZT»
}
}
3. Справочники
3.1 Список кодов ответа на запросы
Таблица 1 Список кодов ответа на запросы
Код ответа Описание Признак
финальности
0 успех да
1 запрос в обработке, повторите запрос позже нет
4 неверный формат идентификатора абонента да
5 идентификатор абонента не найден (ошиблись номером) да
7 прием платежа запрещен провайдером да
8 прием платежа запрещен по техническим причинам да
130 работа с данному сервису не реализована да
153 платеж на проверке в сб нет
155 прием платежа по данному сервису запрещен нет
202 ошибка данных запроса нет
215 транзакция с таким номером уже есть в базе да
220 недостаток средств у агента нет
250 не был пополнен баланс агента да
241 сумма слишком мала да
242 сумма слишком велика да
255 недопустимая дополнительная комиссия нет
300 другая ошибка да
3.2 Типы схем по которой работает услуга
Таблица 2. Типы схем по которой работает услуга
type Описание
0 simple
1 choice
2 invoice