Документация

В общем случае взаимодействие между платежной системой и провайдером услуг можно разделить на два типа:

Оффлайн взаимодействие. Оффлайн - Для провайдеров, чьи абоненты не требовательны к оперативности зачисления средств, возможна реализация взаимодействия в оффлайн режиме, т.е. платежная система отправляет только реестр платежей. Однако для этого метода требуется дополнительное согласования методов проверки существования абонентов – либо периодическая передача в платежную систему существующей номерной емкости, либо методы ключевания счета абонента. Вам не нужен разработчик, и вам не нужно ничего разрабатывать. Имеется возможность выводить информацию о клиенте, сумму долга и т.д, в таком случае необходимо предоставить эти данные в номерной емкости (например, базе данных).

Оперативное (далее – Онлайн) взаимодействие. Онлайн взаимодействие предназначено для динамического определения возможности проведения платежа (проверки номера абонента или его счета) и оперативного зачисления средств на счет абонента провайдера услуг. Вам нужен будет разработчик, которому необходимо разработать API (Application Program Interface) для взаимодействия систем. Методология разработки API представлена далее на этом сайте. Онлайн взаимодействие позволяет расширить функционал в принятии платежа, а уведомление о поступлении платежа приходит в течение нескольких минут. Вам так же будет высылаться реестр платежей.

Онлайн-формат

Руководство разработчика

Введение

Данный документ описывает общие принципы взаимодействия платежной системы с операторами мобильной связи, спутникового телевидения, Internet-провайдерами (далее – провайдерами услуг) с целью обеспечения приема платежей от дилеров платежной системы в пользу провайдера услуг. В разделе описывается транспортная среда взаимодействия, далее – интерфейсы оперативного (онлайн) взаимодействия, сверки платежей и возможности отмены платежа.

Общие положения

Взаимодействие платежной системы с провайдером услуг осуществляется по открытым каналам связи сети общего пользования Internet. Для обмена используется стек протоколов IP/TCP/HTTPS (HTTP over SSL). Защита передаваемых данных от несанкционированного доступа обеспечивается средствами криптографической библиотеки SSL (secure socket layer). Авторизация внешней платежной системы осуществляется за счет применения X.509 клиентского SSL сертификата. Сертификат выдается сертификационным центром провайдера услуг в ответ на “запрос на сертификат” со стороны платежной системы. Длина RSA ключа должна составлять не менее 512 бит. Идентификация внешней платежной системы осуществляется посредством атрибутов клиентского сертификата Субъект и Печать”. В момент установления соединения с сервером провайдера услуг (формирования сессии информационного обмена) должна производиться верификация клиентского сертификата платежной системы по следующим критериям:

сертификат выдан сертификационным центром оператора связи;
электронно-цифровая подпись сертификата верна и сформирована сертификационным центром оператора связи;
не истек срок годности сертификата;
субъект, которому выдан сертификат, является внешней платежной системой.

Важно: SSL желателен, но не обязателен. Можем ограничиваться фильтром по IP и/или basic auth.

Web-сервер провайдера услуг должен обеспечивать возможность использования постоянных соединений, т.е. он должен положительно реагировать на HTTP заголовок Connection: Keep-Alive со стороны внешней платежной системы. Программное обеспечение на стороне сервера оператора связи должно выдавать HTTP заголовок Content-Length, при этом значение должно быть корректным. Платежная система должна быть извещена о значениях следующих параметров:

максимальное количество запросов на одно TCP соединение;
максимальное время жизни TCP соединения;
максимальный интервал времени между двумя HTTP запросами по одному TCP соединению. Запросы от платежной системы к серверу провайдера услуг передаются методом GET http-протокола с параметрами. Запросы могут направляться параллельно, при этом их обработка происходит независимо друг от друга. Т.е. новый запрос может быть отправлен до получения ответа на предыдущий запрос. Ответы возвращаются в виде json-формата. Параметр МАКСИМАЛЬНОЕ ВРЕМЯ ОТВЕТА от сервера провайдера услуг составляет 40 секунд.

Вызов сервера провайдера услуг после установления соединения производится путем запроса страницы по полученному от оператора связи URL с параметрами методом GET. К параметрам применяется url-кодирование. Существует два типа запросов к серверу провайдера услуг:

поиск абонента в биллинговой системе по номеру телефона;
начисление денежных средств на лицевой счет абонента.

Тип запроса определяется значением параметра action. Ответ от сервера представляет собой json-формат, соответствующий шаблону:

1	`{"Code":"","Message":"","AuthCode":"","Date":""}`

Платежная система может посылать запросы с нижеприведенными параметрами:

Входные параметры

Имя параметра	Значение	Назначение	Примечание
Action	Предопределенная строка. Возможные значения: check, payment	Тип запроса	check – поиск абонента (проверка номера), payment – начисление средств
Number	Число, строка	Номер абонента в вашей системе	Тип этого поля может быть уточнен при интеграции платежной системы и провайдера услуг
Amount	Число	Сумма платежа	Сумма платежа в тенге с тиынами. Разделитель ‘.’ (точка)
Receipt	Целое число	Номер платежа в нашей системе	Уникальный для внешней платежной системы номер платежа. Может содержать только цифры. Только для action = payment
Date	Дата и время	Дата и время операции в нашей системе	Дата и время операции по часовому поясу внешней платежной системы в формате YYYY-MM-DDThh:mm:ss. Например,2018-26-12T12:10:06. Только для action=payment

Провайдер услуг может направлять ответы с нижеприведенными параметрами:

Выходные параметры

Имя параметра	Обязательность	Назначение	Примечание
Code	Да	Код ответа	Результат операции
Message	Нет	Сообщение	Читабельная расшифровка ответа. Произвольный текст. Максимальная длина 512 символов.
Date	Нет	Дата и время операции	Дата и время операции по часовому поясу биллинговой системы оператора в формате “YYYY-MM- DDThh:mm:ss”. Например, “2018-26-12T12:10:06”. Только для action=payment
Authcode	Нет	Номер операции (транзакции) с вашей стороны	Уникальный номер платежа в вашей системе. Может содержать только цифры. Только для action=payment
invoice	Нет	Вывод дополнительной информации	Набор дополнительной информации для вывода на интерфейс терминала. Фио, долг, сумма и т.д. Подробнее

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

Коды ответов

Код ответа	Назначение	Примечание
0	Нет ошибки (успех)	Операция прошла успешно (абонент найден, или платеж зачислен)
1	Неизвестный тип запроса	Неизвестное значение поля "action"
2	Абонент не найден	Такого значение поля "number" у вас нету.
3	Неверная сумма платежа	Недопустимое значение суммы платежа. Только для "action"="payment"
4	Неверное значение номера платежа	Недопустимое значение номера платежа. Только для "action"="payment"
5	Неверное значение даты	Недопустимое значение даты операции. Только для "action"="payment"
>=10	Прочие ошибки	Выдается в остальных случаях. Поле "message" обязательно должно содержать расшифровку

Важно: в случае получения запроса на платеж (action = payment) с уже существующим номером receipt, сервер провайдера услуг должен выдать в ответе результат предыдущей попытки платежа с этим номером (code = 0, если предыдущая попытка была успешной). Код авторизации и дата отмены выдаются такие же, как и при предыдущей попытке. Повторной оплаты происходить не должно. Если предыдущая попытка была неудачной, то должна быть предпринята попытка провести платеж. Это заменяет запрос статуса транзакции.

Обработка online-запросов

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

Платежная система отправляет запрос на поиск абонента (action = check) и переходит в режим ожидания ответа на МАКСИМАЛЬНОЕ ВРЕМЯ ОТВЕТА.

1. Если получена ошибка (code <> 0), то клиенту выдается сообщение об ошибке (message). Обслуживание заканчивается.
2. Если ответ не получен в течение МАКСИМАЛЬНОГО ВРЕМЕНИ ОТВЕТА, то клиенту выдается сообщение о недоступности провайдера услуг. Обслуживание заканчивается.

Если получен положительный ответ (code=0),то клиенту выдается сообщение об успешном проведении платежа с указанием кода и даты авторизации провайдера услуг. Обслуживание клиента заканчивается. Платежная система отправляет запрос на платеж (action = payment) и переходит в режим ожидания ответа на МАКСИМАЛЬНОГО ВРЕМЕНИ ОТВЕТА.

1. Если ответ не получен в течение МАКСИМАЛЬНОГО ВРЕМЕНИ ОТВЕТА или получена ошибка (code<> 0), то платежная система повторяет запрос на платеж (action = payment) с идентичным номером receipt до получения однозначного положительного ответа. Количество попыток ограничено.

Примеры ответов

Поиск абонента по номеру счёта

Запрос:	https://<host>/<path>?action=check&number=1166438476
Ответ:	{"Code":"0","Message":"Абонент существует"}

Неудачный поиск абонента по номеру счёта

Запрос:	https://<host>/<path>?action=check&number=8960256140
Ответ:	{"Code":"2","Message":"Такого абонента не существует"}

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

Запрос:	https://<host>/<path>?action=payment&number=42342572526&amount=25.34&receipt=3568264&date=2018-26-12T15:53:00
Ответ:	{"Code":"0","Message":"Платёж принят","AuthCode":"133","Date":"2018-09-01T15:53:00"}

Повторный запрос

Запрос:	https://<host>/<path>?action=payment&number=42342572526&amount=25.34&receipt=3568264&date=2018-26-12T15:53:00
Ответ:	{"Code":"0","Message":"Платеж уже был принят","AuthCode":"133","Date":"2018-09-01T15:53:00"}

Вывод дополнительной информации

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

Важно: Вариант выведения дополнительной информации доступен на ответ запроса онлайн-проверки.
Важно: Просим вас соответствовать форматам, представленным нами.

Схема оплаты может быть:

Контрактной - когда выводятся варианты оплаты. Обычно подходит МФО. Пример:

Подтверждение - когда вы присылаете дополнительную информацию о клиенте, и мы выводим её на экран, чтобы клиент мог удостовериться, что он верно ввёл свои данные.

Динамическая - когда вы присылаете, то что хотите вывести.

Отмена и статус платежа

Последовательность действий для отмены платежа

Отмена в автоматическом режиме не используется, только через call-центр.

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

Проверка состояния платежа в автоматическом режиме не используется, только через call-центр, наш сайт, терминалы или телеграм-бот.

Итоговый реестр платежей

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

Итоговый реестр платежей представляет собой текстовый файл (или любой другой формат, по умолчанию excel-файл), содержащий список платежей, принятых внешней платежной системой в пользу провайдера услуг. В итоговом реестре содержатся все успешно принятые платежи обработка которых завершилась за календарный день за отчетную дату за период времени с 00:00:00 по 23:59:59 по часовому поясу внешней платежной системы. Платежи, отсутствующие в данном файле, но присутствующие у провайдера услуг, считаются не прошедшими и должны быть отменены. Платежи, присутствующие в данном файле, но отсутствующие у провайдера услуг, считаются прошедшими и должны быть проведены провайдером услуг при условии возможности проведения такого платежа. Реестр платежей высылается в любое удобное для вас время (по умолчанию в 2-00).

Пример текстового файла

Имя файла – . Тема (заголовок) электронного письма – <Платежи за dd.MM.yyyy: Идентификатор провайдера> dd.MM.yyyy – соответствует дате отчета. Файл состоит из текстовых строк переменной длины в ASCII, кодовая страница windows-1251. Каждая строка заканчивается символами “перевод строки”, “возврат каретки” (0x0D, 0x0A) и содержит информацию об одном платеже. Каждая строка содержит следующие поля: Сумма платежа указываются в тенге с тиынами, разделитель – точка. Поля разделяются знаком табуляции (0x09).

№	Наименование поля	Формат поля	Примечание
1	Номер счета (или телефона) абонента	Строка	Что клиент введёт на терминале
2	Тип	Число	Тип абонента. Согласовывается с провайдером услуг, если данный провайдер использует систему для проведения платежей за несколько видов услуг
3	Дата и время	YYYY-MM-DDThh:mm:ss	Дата время операции по часовому поясу платежной системы (из запроса)
4	Сумма платежа	Число	Целая часть: не более 7 цифр (тенге); Дробная часть: не более 2 цифр (тиын, может отсутствовать). В качестве разделителя дробной части используется точка
5	Номер платежа	Число	Уникальный номер платежа в платежной системе (receipt)

Пример Excel-файла

Имя файла – <astanaplatYYYYMMDD.xlsx>

Тема (заголовок) электронного письма – <Платежи за dd.MM.yyyy: Идентификатор провайдера> dd.MM.yyyy – соответствует дате отчета.

Файл состоит из одного листа Excel, в котором присутствуют следующие поля:

№	Наименование поля	Формат поля	Примечание
1	Договор/лицевой счет	Формула	Что клиент введёт на терминале
2	Тип	Число	Тип абонента. Согласовывается с провайдером услуг, если данный провайдер использует систему для проведения платежей за несколько видов услуг
3	Дата/время	YYYY-MM-DDThh:mm:ss	Дата время операции по часовому поясу платежной системы (из запроса)
4	Сумма платежа	Число	Целая часть: не более 7 цифр (тенге); Дробная часть: не более 2 цифр (тиын, может отсутствовать). В качестве разделителя дробной части используется запятая
5	№ транзакции	Число	Уникальный номер платежа в платежной системе (receipt)