Общие принципы протокола
Взаимодействие Системы и провайдера строится в режиме “запрос-ответ”, где инициатором запроса всегда является Система, а отвечающей стороной – провайдер.
Каждый платеж в Системе имеет уникальный идентификатор, который передается в каждом запросе. По этому идентификатору производится дальнейшая сверка взаиморасчетов и решение спорных вопросов.
При обработке запроса от Системы, провайдер должен выполнить требуемую операцию, а затем ответом передать Системе данные (если это требуется) и результат выполнения операции.
Golang sample: https://github.com/alifpay/providers
Требования к интерфейсу провайдера
-
Интерфейс должен принимать запросы по протоколу HTTPS
-
Интерфейс должен обрабатывать параметры, передаваемые системой методом HTTP POST - в теле запроса в виде формате JSON в кодировке UTF-8.
-
Интерфейс должен формировать ответ системе в формате JSON в кодировке UTF-8.
-
Скорость ответа не должна превышать 60 секунд, в противном случае система разрывает соединение по таймауту.
-
Если предполагаемое количество платежей за услуги подключаемого провайдера ожидается интенсивным (до 10 платежей в минуту и более), необходимо, чтобы интерфейс поддерживал многопоточную коммуникацию
Запрос check
Параметры запроса
При получении запроса check провайдер должен проверить наличие в своей базе абонента с указанным идентификатором и выполнить внутренние проверки идентификатора в соответствии с принятой логикой пополнения лицевых счетов через платежные Системы.
| Параметр | Условие | Описание |
|---|---|---|
| action | Обязательно | Идентификация типа запроса: осуществить проверку счета абонента. Всегда равен check |
| id | Обязательно | Идентификатор платежа в Системе. В базе провайдера не должно содержаться двух успешно проведенных платежей с одним и тем же идентификатором платежа. При получении запроса со значением id, уже существующим в базе провайдера, провайдер должен вернуть результат обработки предыдущего запроса. |
| account | Обязательно | Идентификатор абонента в информационной системе провайдера |
| srv_id | Опционально | Идентификатор услуги, предоставляемой провайдером (Используется, если провайдер предоставляет более 1 услуги) |
| info | Опционально | Дополнительные параметры, передаваемые провайдеру |
Параметры ответа
В ответе интерфейс провайдера должен вернуть JSON-документ, со следующими полями:
| Параметр | Условие | Описание |
|---|---|---|
| code | Обязательно | Код результата операции (code=302 в случае существования абонента и возможности принятия платежа) |
| id | Обязательно | Идентификатор платежа в Системе. |
| info_for_client | Опционально | Информация для отображения клиенту при совершении платежа |
| amount | Опционально | Сумма к начислению платежа в формате 100.50 |
Check Пример запроса
POST
Accept: application/json
Host: service.provider.com:443
Content-type: application/json; charset=utf-8
Authorization: VVNFUk5BTUU6UEFTU1dPUkQ=
{
"id": 12345132564875,
"action": "check",
"account": "123000"
}
// Дополнительные параметры, передаваемые провайдеру
{
"id": 12345132564875,
"action": "check",
"account": "123000"
"info":{"fieldId1":"value1","fieldId2":"value2"}
}
// Check Пример ответа
{
"code": 302
"id": 12345132564875
}
// Дополнительные параметры,
{
"code": 302
"id": 12345132564875,
"info_for_client": "Баланс: 50.30 смн\\nСрок оплаты: 25.10.2020"
}
Запрос pay
При получении запроса pay провайдер должен произвести пополнение баланса абонента. В базе провайдера не должно содержаться двух успешно проведенных платежей с одним и тем же идентификатором платежа (id – идентификатор платежа в Системе). При получении запроса со значением id, уже существующим в базе провайдера, провайдер должен вернуть результат обработки предыдущего запроса.
Параметры запроса
| Параметр | Условие | Описание |
|---|---|---|
| action | Обязательно | Идентификация типа запроса: Запрос pay. Всегда равен pay |
| id | Обязательно | Идентификатор платежа в Системе. В базе провайдера не должно содержаться двух успешно проведенных платежей с одним и тем же идентификатором платежа. При получении запроса со значением id, уже существующим в базе провайдера, провайдер должен вернуть результат обработки предыдущего запроса. |
| account | Обязательно | Идентификатор абонента в информационной системе провайдера |
| amount | Обязательно | Сумма операции в формате 100.50 |
| time | Опционально | Дата операции (Пример: 2006-01-02T15:04:05Z) |
| srv_id | Опционально | Идентификатор услуги, предоставляемой провайдером (Используется, если провайдер предоставляет более 1 услуги) |
| info | Опционально | Дополнительные параметры, передаваемые провайдеру |
Параметры ответа
В ответе интерфейс провайдера должен вернуть JSON-документ, со следующими полями:
| Параметр | Условие | Описание |
|---|---|---|
| code | Обязательно | Код результата операции (code=200 в случае успешной регистрации платежа) |
| id | Обязательно | Идентификатор платежа в Системе. |
| response_id | Обязательно | Уникальный номер операции пополнения баланса абонента (в информационной системе провайдера) |
// Pay Пример запроса
POST
Accept: application/json
Host: service.provider.com:443
Content-type: application/json; charset=utf-8
Authorization: VVNFUk5BTUU6UEFTU1dPUkQ=
{
"id": 12345132564875,
"action": "pay",
"account": "123000",
"amount": 100.50,
"time": "2006-01-02T15:04:05Z"
}
// Pay Дополнительные параметры, передаваемые провайдеру
{
"id": 12345132564875,
"action": "pay",
"account": "123000",
"amount": 100.50,
"time": "2006-01-02T15:04:05Z"
"info":{"fieldId1":"value1","fieldId2":"value2"}
}
// Pay Пример ответа
{
"code": 200
"id": 12345132564875,
"response_id": "4545487"
}
Запрос status
При получении запроса status провайдер должен проверить статус платежа.
Параметры запроса
| Параметр | Условие | Описание |
|---|---|---|
| action | Обязательно | Идентификация типа запроса: Запрос status. Всегда равен status |
| id | Обязательно | Идентификатор платежа в Системе. |
Параметры ответа
В ответе интерфейс провайдера должен вернуть JSON-документ, со следующими полями:
| Параметр | Условие | Описание |
|---|---|---|
| code | Обязательно | Код результата операции |
| id | Обязательно | Идентификатор платежа в Системе. |
| response_id | Обязательно | Уникальный номер операции пополнения баланса абонента (в информационной системе провайдера) |
Авторизации запросов
В заявке на подключение провайдер должен задать идентификатор (логин) и секретный пароль к нему, используемые для авторизации при запросах.
К запросу добавляется HTTP-заголовок Authorization. В заголовке указывается строка пара “логин:пароль”, закодированная в BASE64:
Authorization: BASE64(“Login:Password”)
Error Codes
Результаты выполнения запросов
При обработке запросов от Системы провайдер должен сопоставить все возникающие в его приложении ошибки с приведенным ниже списком и возвращать соответствующие коды в поле “code”.
В списке отдельно отмечены фатальные и нефатальные ошибки: Фатальная ошибка означает, что повторная отправка запроса с теми же параметрами приведет к 100% повторению той же ошибки; следовательно, Система прекращает обработку клиентского запроса и завершает его с ошибкой. Нефатальная ошибка означает для Системы, что повторение запроса с теми же параметрами через некоторый промежуток времени, возможно, приведет к успеху. При получении нефатальной ошибки Система будет повторять запросы, увеличивая интервал, пока операция не завершится успехом или фатальной ошибкой, либо пока не истечет срок жизни платежа в Системе (24 часа).
Например, отсутствие связи с сервером провайдера является нефатальной ошибкой. Отсутствие в ответе поля “code” является фатальной ошибкой.
| Код | Описание | Фатальность | Check | Pay | Status |
|---|---|---|---|---|---|
| 200 | Успешно | Да | - | + | + |
| 203 | Платеж отклонен | Да | - | + | + |
| 302 | Абонент найден | Да | + | - | - |
| 404 | Идентификатор абонента не найден (Ошиблись номером) | Да | + | + | + |
| 104 | Транзакция не существует | Да | - | - | + |
| 107 | Транзакция уже существует | Нет | - | + | - |
| 108 | Успешно проведен(дубликат) | Да | - | + | - |
| 201 | В обработке | Нет | - | + | + |
| 303 | Услуга временно недоступна,(неудачный) | Да | + | + | + |
| 305 | Недостаточно средств на счету | Нет | - | + | - |
| 400 | Ваш запрос некорректен (ошибка данных, формата) | Да | + | + | + |
| 405 | Сумма вне диапазона | Да | + | + | - |
| 500 | Внутренняя ошибка сервера (неудачный) | Да | + | + | - |
| 503 | Сервис недоступен (неудачный) | Да | + | + | + |
| 520 | Неизвестная ошибка | Нет | + | + | + |
| 401 | Авторизация не удалась | Да | + | + | + |
Example
Golang sample: https://github.com/alifpay/providers