API для интеграции с деревом услуг EРИП
Содержание
- Требования к API запросов
- Получение дерева ЕРИП
- Отправка параметров required_attributes, полученных в ответе от конечного узла
- Регистрация платежа, если у мерчанта сохранены конечный узел и лицевой счет клиента
- Получение токена карты
- Отмена блокировки средств
- Авторизация платежа и списание средств у клиента
Требования к API запросов
Все запросы должны:
- Иметь авторизацию типа Basic c ID магазина и секретным ключем магазина как имя пользователя и пароль соответственно, иметь заголовки
Content-Type: application/jsonиAccept: application/json - Использовать SSL соединение с 128-bit (или более сложным) шифрованием
- Использовать кодировку UTF-8.
Получение дерева ЕРИП
Отправьте POST запрос на https://api.bepaid.by/beyag/gateways/komplat/get_pay_list.
В ответе будет получен набор узлов дерева ЕРИП. Для продвижения в глубь узла дерева, необходимо отправить новый запрос с pay_code узла, в который необходимо зайти. Запросы выполняются до тех пор, пока клиент не дойдет до конечного узла (до услуги, за которую клиент хочет заплатить).
Если узел в запросе является конечным, то в ответе будут возвращены параметры, которые клиент должен заполнить для завершения регистрации платежа.
Параметры запроса
| Параметр | Тип | Описание |
|---|---|---|
| terminal_id * обязательный |
string | ID терминала. Уникальный для каждого мерчанта. |
| pay_code * обязательный |
string | Код узла ЕРИП. Код начального узла: 11000000000 |
| di_type * обязательный |
string | Код типа узла ЕРИП. Код типа начального узла: 9191 |
| test | true или false. Запрос будет тестовым, если значение true |
Пример запроса
{
"terminal_id": "10000002",
"pay_code": "11000000000",
"di_type": "9191"
}
Параметры ответа, если узел в запросе не является конечным
| Параметр | Описание |
|---|---|
| code | Код узла ЕРИП |
| name | Имя узла |
| di_type | Код типа узла ЕРИП |
Пример ответа, если узел в запросе не является конечным
[
{
"code":"11000304194",
"name":"Банковские, финансовые услуги",
"di_type":"9120"
},
{
"code":"11000300001",
"name":"БЕЛТЕЛЕКОМ",
"di_type":"9120"
},
{
"code":"11000300002",
"name":"Домофонные системы, Видеонаблюдение",
"di_type":"9120"
},
{
"code":"11000300088",
"name":"Интернет, Телевидение, Телефония",
"di_type":"9120"
},
{
"code":"11000300004",
"name":"Интернет-магазины/сервисы",
"di_type":"9120"
},
{
"code":"11000300005",
"name":"Коммунальные платежи",
"di_type":"9120"
},
{
"code":"11000300006",
"name":"Мобильная связь",
"di_type":"9120"
},
{
"code":"11000304212",
"name":"Налоги",
"di_type":"9120"
},
{
"code":"11000304351",
"name":"Стоянки, гаражи, парковки",
"di_type":"9120"
},
{
"code":"11000304168",
"name":"Суды, Юстиция, Юридические услуги",
"di_type":"9120"
}
]
Параметры ответа, если узел в запросе является конечным
| Параметр | Тип | Описание |
|---|---|---|
| code * обязательный |
string | Код конечного узла ЕРИП. Соответствует параметру pay_code из запроса. |
| name * обязательный |
string | Имя узла ЕРИП, по которому производится оплата. |
| di_type * обязательный |
string | Код типа узла ЕРИП. |
| information * обязательный |
string | Сообщение ЕРИП для показа клиенту. |
| customer_name | object | Секция с параметрами имени клиента, возвращаемая сервисом ЕРИП. Если ЕРИП не вернул ФИО покупателя - возвращается null. |
| first_name * обязательный |
string | Имя клиента. |
| middle_name * обязательный |
string | Отчество клиента. |
| last_name * обязательный |
string | Фамилия клиента. |
| required_attributes * обязательный |
array | Массив с параметрами ЕРИП, которые должны быть заполнены клиентом и переданы снова в ЕРИП для регистарции платежа. |
| information_attributes * обязательный |
array | Массив c параметрами ЕРИП для показа клиенту. |
| erip_session_id * обязательный |
string | Идентификатор сессии ЕРИП. |
Пример ответа, если узел в запросе является конечным
{
"code": "10002642301",
"name": "оплата по номеру телефона",
"di_type": "9191",
"information": "Введите 9 цифр тестового номера телефона",
"customer_name": {
"first_name": null,
"middle_name": null,
"last_name": null
},
"required_attributes": [
{
"code": "1001",
"name": "тестовый номер телефона",
"min_length": "9",
"max_length": "9"
}
],
"information_attributes": [],
"erip_session_id": "00000000000121603908-01-FBBD95"
}
Отправка параметров required_attributes, полученных в ответе от конечного узла
Отправьте POST запрос на https://api.bepaid.by/beyag/gateways/komplat/get_pay_list со следующими параметрами:
| Параметр | Тип | Описание |
|---|---|---|
| terminal_id * обязательный |
string | ID терминала. Уникальный для каждого мерчанта. |
| pay_code * обязательный |
string | Код узла ЕРИП. Код конечного узла. |
| di_type * обязательный |
string | Код типа узла ЕРИП. Код конечного узла. |
| erip_session_id * обязательный |
string | Идентификатор сессии ЕРИП. |
| attributes | object | В секции указываются заполняемые клиентом параметры из массива required_attributes, полученного в ответе от конечного узла. |
| test | true или false. Запрос будет тестовым, если значение true. |
Пример запроса
{
"terminal_id": "10000002",
"pay_code": "10004372291",
"di_type": "9191",
"erip_session_id": "00000000005698332392-01-A7512E",
"attributes": {
"1001": "0291234567"
}
}
Параметры ответа
| Параметр | Тип | Описание |
|---|---|---|
| code * обязательный |
string | Код конечного узла ЕРИП. Соответствует параметру pay_code из запроса. |
| name * обязательный |
string | Имя узла, по которому производится оплата. |
| di_type * обязательный |
string | Код типа узла ЕРИП. |
| billed_amount * обязательный |
string | Выставленная сумма. Если параметр fixed_amount=true, то изменить сумму нельзя. Если fixed_amount=false, то интерфейс должен позволять клиенту изменять сумму. |
| fixed_amount * обязательный |
boolean | true или false. Если true, сумму billed_amount нельзя изменить. |
| currency * обязательный |
string | Валюта в ISO-4217 формате, например BYN. |
| information * обязательный |
string | Информация о лицевом счете от ЕРИП для показа клиенту. |
| information_attributes * обязательный |
array | Массив c информационными параметрами от ЕРИП для показа клиенту. |
| customer_name | object | Секция с параметрами имени клиента. Если имя клиента не сохранено, возвращается null. |
| first_name * обязательный |
string | Имя клиента. |
| middle_name * обязательный |
string | Отчество клиента. |
| last_name * обязательный |
string | Фамилия клиента. |
| erip_fine * обязательный |
string | Сумма пени ЕРИП. |
| erip_commision * обязательный |
string | Сумма комиссии ЕРИП. |
| erip_session_id * обязательный |
string | Идентификатор сессии ЕРИП. |
Пример ответа
{
"code": "10004372291",
"name": "Коммунальные платежи",
"di_type": "9191",
"billed_amount": "122.43",
"fixed_amount": true,
"currency": "BYN",
"information": null,
"information_attributes": [
{
"name": "Дата выставления",
"value": "12.03.2021"
},
{
"name": "Период",
"value": "02.2021"
},
{
"name": "Начислено",
"value": null
},
{
"name": "Начислено",
"value": "122,11 BYN"
},
{
"name": "Долг по пене",
"value": "0,32 BYN"
}
],
"customer_name": {
"first_name": null,
"middle_name": null,
"last_name": null
},
"erip_fine": "0.00",
"erip_commision": "0.00",
"erip_session_id": "00000000005698332392-00-0F0D24"
}
Регистрация платежа, если у мерчанта сохранены конечный узел и лицевой счет клиента
Способ используется для реализации сохранения шаблона платежа ЕРИП. Таким образом, клиенту не придется перед каждым платежом продвигаться в глубь дерева ЕРИП.
Параметры для запроса должны хранится в базе данных Мерчанта.
Отправьте POST запрос на https://api.bepaid.by/beyag/gateways/komplat/get_pay_list со следующими параметрами:
| Параметр | Тип | Описание |
|---|---|---|
| terminal_id * обязательный |
string | ID терминала. Уникальный для каждого мерчанта. |
| pay_code * обязательный |
string | Код узла ЕРИП. |
| di_type * обязательный |
string | Код типа узла ЕРИП. |
| erip_session_id * обязательный |
string | Идентификатор сессии ЕРИП. |
| customer | object | Секция для передачи ID клиента. |
| personal_account | string | ID лицевого счета ЕРИП. |
| erip_account | string | Идентификатор в системе ЕРИП. |
| test | boolean | true или false. Запрос будет тестовым, если значение true. |
Пример запроса
{
"terminal_id": "10000002",
"pay_code": "10004345361",
"di_type": "9191",
"customer": {
"personal_account": "28923485423"
}
}
Параметры ответа
Параметры ответа аналогичны, указанным в разделе Отправка параметров required_attributes, полученных в ответе от конечного узла.
Пример ответа
{
"code": "10004345361",
"name": "Абонентская плата",
"di_type": "9191",
"billed_amount": "0.00",
"fixed_amount": false,
"currency": "BYN",
"information": "Введите лицевой счет Иван Иванович Иванов г. Минск, ул. Селицкого, д. 1, кв. 11, 1 под., 1 эт.-",
"information_attributes": [
{
"name": "Лицевой счет",
"value": "112233"
},
{
"name": "Период",
"value": "0221"
}
],
"customer_name": {
"first_name": null,
"middle_name": null,
"last_name": null
},
"erip_fine": "0.00",
"erip_commision": "0.00",
"erip_session_id": "00000000005656285468-00-664734"
}
Получение токена карты
Получить токен карты можно заранее, например, при регистрации клиента в приложении предложить привязать карту. Далее с полученным токеном проводить платежи ЕРИП.
Запрос на получение токена карты аналогичен описанному в разделе Авторизация.
Отмена блокировки средств
Запрос используется после успешной авторизации для отмены блокировки средств после авторизации.
Запрос на отмену блокировки средств аналогичен описанному в разделе Отмена авторизации.
Авторизация платежа и списание средств у клиента
Запрос аналогичен, описанному в разделе Авторизация.
После успешной авторизации, автоматически будет произведено списание средств у клиента.
Описание параметров ЕРИП опубликовано в request.additional_data.komplat в описании запроса на Авторизацию.
Пример запроса
{
"request": {
"amount": 100,
"currency": "BYN",
"description": "Test transaction",
"tracking_id": "my_tracking_id",
"credit_card": {
"token": "144da09d-078e-4aca-8919-032c87763b55"
},
"additional_data": {
"komplat": {
"pay_code": "10000156731",
"di_type": "9191",
"erip_session_id": "00000000000117153888-00-46F3AE"
}
}
}
}