Перейти к содержанию

API для интеграции с деревом услуг EРИП

Содержание

Info

Обратите внимание, что при оплате с помощью параметров дерева услуг ЕРИП нельзя использовать транзакцию типа оплата (payment) – используйте только тип транзакции авторизация (authorization).

Требования к 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
 boolean
true или false. Запрос будет тестовым, если значение true.
Пример запроса 
{
    "terminal_id": "10000002",
    "pay_code": "11000000000",
    "di_type": "9191"
}

Параметры ответа, если узел в запросе не является конечным
code
 string
Код узла ЕРИП.
name
 string
Имя узла.
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
Сообщение ЕРИП для показа покупателю.
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
 boolean
Запрос будет тестовым, если значение 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 информационными параметрами от ЕРИП для показа покупателю.
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
Идентификатор сессии ЕРИП.
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"
}

Получение токена карты

Получить токен карты можно заранее, например, при регистрации покупателя в приложении предложить привязать карту. Далее с полученным токеном проводить платежи ЕРИП.

Запрос на получение токена карты аналогичен описанному в разделе Авторизация.

Отмена блокировки средств

Запрос используется после успешной авторизации для отмены блокировки средств после авторизации.

Запрос на отмену блокировки средств аналогичен описанному в разделе Отмена авторизации.

Авторизация платежа и списание средств у покупателя

Info

Обратите внимание, что при оплате с помощью параметров дерева услуг ЕРИП нельзя использовать транзакцию типа оплата (payment) – используйте только тип транзакции авторизация (authorization).

Запрос аналогичен описанному в разделе Авторизация.

После успешной авторизации, автоматически будет произведено списание средств у покупателя.

Описание параметров ЕРИП опубликовано в 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"
      }
    }
  }
}