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

Создание счёта в ЕРИП

Требования к API запросам

Запросы на выставление платёжных требований в ЕРИП к API bePaid должны:

Запрос на оплату через ЕРИП отправляется в виде JSON-сообщения. В случае принятия запроса системой, возвращается ответ со статусом оплаты pending или permanent.

В случае возникновения ошибки, возвращается статус error и описание ошибки.

Как работает оплата через ЕРИП

После получения от bePaid на ваш запрос ответа со статусом pending или permanent об успешном создании счёта в ЕРИП, bePaid и мы находимся в стадии ожидания подтверждения оплаты от ЕРИП.

Когда оплата проходит и bePaid получает от АИС <<Расчёт>> уведомление об этом, то статус платежа меняется на successful или failed и высылается уведомление об оплате на скрипты вашей IT-системы, а платеж с обновлённым статусом отображается в личном кабинете.

Если оплата началась, но по каким-то причинам не завершилась, платёжное требование находится в статусе start 30 минут и не доступно для повторной оплаты.

По истечении 30 минут, оно автоматически вернется в статус pending и будет снова доступно для оплаты.

Статусы платёжных требований

Статус Описание
pending Платежное требование создано успешно. Находимся в ожидании оплаты
auto_created Платёжное требование, созданное при авансовой оплате или при оплате постоянного платежного требования. Находимся в ожидании оплаты
expired Платёжное требование не оплачено и срок оплаты истёк или было созданно новое платёжное требование с тем же номером заказа/счёта или договора.
permanent Постоянно действующее платёжное требование на оплату. По данному счёту можно платить сколько угодно раз.
successful Оплата произведена успешно.
failed Оплата произведена не успешно.
deleted Платёжное поручение удалено торговцем.

Создать платёжное требование

Отправьте POST запрос на https://api.bepaid.by/beyag/payments со следующими параметрами:

Параметры запроса

Параметр Тип Описание
request object
amount * обязательный
integer Сумма платежа в копейках, например 32.45 BYN должны быть отправлены как 3245. Если amount == 0 и payment_method.type == erip, то плательщик может оплатить произвольную сумму в границах лимитов, установленных ЕРИП, согласно анкеты услуги.
currency * обязательный
string Валюта BYN
description * обязательный
string Описание заказа.
email * условно обязательный
string Адрес электронной почты покупателя.

Параметр обязателен, если требуется отправить покупателю уведомление о созданном платежном требовании по электронной почте.
ip string IP адрес покупателя. Используйте 127.0.0.1, если не знаете IP адреса покупателя.
order_id * обязательный
string 12 циферный номер заказа в системе торговца. Идентификационный номер заказа в системе для отслеживания оплаченного заказа после получения подтверждения.
expired_at string Время, до которого действителен платёж. По умолчанию бессрочно. Формат: ISO 8601. Формат YYYY-MM-DDThh:mm:ssTZD, где YYYY – год (например, 2023), MM – месяц (например, 02), DD – день (например, 09), hh – часы (например, 18), mm – минуты (например, 20), ss – секунды (например, 45), TZD – временная зона (+hh:mm или –hh:mm), например, +03:00 для Минска.
notification_url string URL, на который будут приходить уведомления торговцу. Если не передан, уведомления не будут доставляться.
tracking_id string Параметр для передачи внутренней информации об оплате (номер заказа или покупателя и тд), которая в дальнейшем позволит отследить оплату в пришедшем уведомлении. Если не передан, то будет установлен в значение order_id
customer object Секция информации о покупателе.
first_name string Имя покупателя. Максимальная длина: 30 символов.
middle_name string Отчество покупателя. Максимальная длина: 30 символов.
last_name string Фамилия покупателя. Максимальная длина: 30 символов.
country string Страна покупателя в ISO 3166-1 alpha-2 формате
city string Город покупателя. Максимальная длина: 60 символов.
zip string Почтовый индекс покупателя. Максимальная длина: 20 символов
address string Адрес для выставления счёта. Максимальная длина: 250
phone string(30) Номер телефона покупателя.

Параметр обязателен, если требуется отправить покупателю уведомление о созданном платежном требовании по SMS.
additional_data object Секция, содержащая дополнительную информацию о платеже.
notifications array Типы уведомлений, отправляемых покупателям при создании платежных требований.

Возможные значения:
sms - уведомления по SMS;
email - уведомления по электронной почте;
пустое значение - уведомления клиентам рассылаться не будут. Установлено по умолчанию.
Должен быть представлен как массив строк, например ["sms"].
receipt_text array Текст, который будет добавлен в письмо клиенту. Должен быть представлен как массив строк, например ["Первая строка", "Вторая строка"]
payment_method object Секция платежного метода
type * обязательный
string erip
permanent boolean true - создает постоянно действующее, а не однократное платёжное требование в ЕРИП
editable_amount boolean true- сумма разрешается для редактирования, и плательщик в момент оплаты может изменить сумму платежа в ЕРИП
account_number * обязательный
string(30) Идентификатор заказа/услуги/договора, для оплаты через ЕРИП. Данное значение необходимо ввести покупателю, чтобы начать процесс оплаты заказа/услуги/договора через ЕРИП. Если будет прислан запрос на оплату с account_number, который уже есть в системе, то предыдущее требование на оплату получит статус expired
service_no * условно обязательный
integer(8) Код услуги ЕРИП, присвоенный bePaid. Передается, если у вас к одному магазину подключено несколько ЕРИП услуг
service_info array Массив строк информации, которая будет показана плательщику перед подтверждением оплаты через ЕРИП и описывающая за что происходит оплата. Например, Оплата по договору 123 за январь
receipt array Массив строк информации, которая будет отображена на чеке-подтверждении оплаты через ЕРИП. Например, Спасибо за оплату
instruction array Массив строк информации, которая описывает путь в дереве ЕРИП для нахождения платежного поручения.
erip_devices array Массив данных о счётчиках, каждый элемент которого имеет следующую структуру:
name string Наименование счётчика, например Холодная вода
item_unit string Единица измерения счётчика, например м3
rank integer Разрядность счётчика (количество целых единиц), например 4
value integer Текущие показания счётчика, например 1234
rate float Стоимость единицы измерения счётчика, например 0.4392
Пример запроса
{
  "request": {
    "amount": 1000,
    "currency": "BYN",
    "description": "Оплата заказа #123",
    "email": "ivanpetrov@example.com",
    "ip": "127.0.0.1",
    "order_id": 123456789012,
    "tracking_id": "AB8923",
    "notification_url": "http://merchant.example.com",
    "customer": {
      "first_name": "Иван",
      "middle_name": "Иванович",
      "last_name": "Петров",
      "country": "BY",
      "city": "Минск",
      "zip": "220000",
      "address": "ул. Независимости, 1",
      "phone": "+375172000000"
    },
    "payment_method": {
      "type": "erip",
      "account_number": "123",
      "service_no": "99999999",
      "service_info": [
        "Оплата заказа 123"
      ],
      "receipt": [
        "Спасибо за оплату заказа 123"
      ]
    },
    "additional_data":{
      "receipt_text": ["Первая строка", "Вторая строка"],
      "notifications": [
        "sms"
      ]
    }
  }
}
Пример запроса со счётчиком
{
  "request": {
    "amount": 1000,
    "currency": "BYN",
    "description": "Оплата водоснабжения счётчика #123",
    "email": "ivanpetrov@example.com",
    "ip": "127.0.0.1",
    "order_id": 123456789012,
    "tracking_id": "AB8923",
    "notification_url": "http://merchant.example.com",
    "customer": {
      "first_name": "Иван",
      "middle_name": "Иванович",
      "last_name": "Петров",
      "country": "BY",
      "city": "Минск",
      "zip": "220000",
      "address": "ул. Независимости, 1",
      "phone": "+375172000000"
    },
    "payment_method": {
      "type": "erip",
      "account_number": "123",
      "service_no": "99999999",
      "service_info": [
        "Оплата водоснабжения счётчика #123"
      ],
      "receipt": [
        "Спасибо за оплату"
      ],
      "erip_devices": [
        {
          "name":"Холодная вода",
          "item_unit":"м3",
          "rank":"4",
          "value":"1234",
          "rate":"0.4392"
        }
      ]
    },
    "additional_data":{
      "receipt_text": ["Первая строка", "Вторая строка"],
      "notifications": [
        "sms"
      ]
    }
  }
}

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

Если платежный запрос принят успешно, ответ будет выдан в виде JSON-сообщения, содержащего status. Такое же сообщение будет отправлено в уведомлении на notification_url после проведения оплаты.

Параметр Тип Описание
transaction object
status string Статус платежа.
message string Сообщение системы
type string payment
amount integer Сумма платежа в копейках.
currency string Валюта транзакции.
description string Описание заказа.
uid string uid транзакции.
ID string ID транзакции.
order_id string Значение order_id из платежного запроса.
tracking_id string Значение tracking_id или order_id из платежного запроса.
expired_at string Дата, до которой действует платёж. Данный параметр отсутствует, если у платежа нет срока действия. Смотрите описание формата в expired_at запроса на оплату.
paid_at string Дата, когда был оплачен платёж. Данный параметр отсутствует, если платеж еще не оплачен. Смотрите описание формата в expired_at запроса на оплату.
created_at string Время создания платёжного требования.
language string Значение параметра language из запроса или en по умолчанию.
test boolean true, если платежный запрос является тестовым.
payment_method_type string erip
additional_data object Секция, содержащая дополнительную информацию о платеже.
notifications array Типы уведомлений, отправляемых покупателям при создании платежных требований.
receipt_text array Массив строк текста, который будет добавлен в письмо клиенту.
billing_address object Секция информации о покупателе.
first_name string Имя покупателя.
middle_name string Отчество покупателя.
last_name string Фамилия покупателя.
country string Страна покупателя.
city string Город покупателя.
zip string Почтовый индекс или zip-код покупателя.
address string Адрес покупателя.
phone string Телефонный номер покупателя.
customer object Секция информации о покупателе.
ip string IP адрес покупателя.
email string Электронная почта покупателя.
payment object Секция оплаты.
ref_id string Идентификационный номер транзакции в ЕРИП.
message string Сообщение ЕРИП.
status string Статус операции в ЕРИП.
gateway_id string ID внутреннего платежного шлюза.
erip object Данные о ЕРИП платеже.
request_id integer Номер запроса в ЕРИП.
service_no integer Код услуги ЕРИП, присвоенный bePaid.
account_number string Идентификатор заказа/услуги/договора, для оплаты через ЕРИП.
transaction_id integer Номер операции в ЕРИП.
instruction array Массив строк информации, которая описывает путь в дереве ЕРИП для нахождения платежного поручения.
service_info array Массив строк информации, которая будет показана плательщику перед подтверждением оплаты через ЕРИП и описывающая, за что происходит оплата.
receipt array Массив строк информации, которая будет отображена на чеке-подтверждении оплаты через ЕРИП.
agent_code integer Код платежного агента, принявшего платеж.
agent_name string Имя платежного агента, принявшего платеж.
service_no_erip integer Код услуги, присвоенный ЕРИП.
qr_code_raw string Закодированные в base64 данные для генерации QR-кода.
qr_code string Закодированная в base64 PNG картинка QR-кода. Для отображения QR-кода на сайте нужно вставить значение qr_code в img HTML тэг: <img src="здесь значение qr_code">.
Пример ответа
{
  "transaction":{
    "status":"pending",
    "message":"Требование на оплату счёта создано.",
    "type":"payment",
    "id":"8759cf84-e56d-44b7-a8ae-62640f6402c4",
    "uid":"8759cf84-e56d-44b7-a8ae-62640f6402c4",
    "order_id":"100000003495",
    "amount":22000,
    "currency":"BYN",
    "description":"Оплата заказа #123",
    "tracking_id":"AB8923",
    "created_at":"2015-12-07T14:21:24.420Z",
    "expired_at":"2016-12-07T14:21:240Z",
    "paid_at":"2016-12-07T14:40:120Z",
    "test":true,
    "payment_method_type":"erip",
    "billing_address":{
        "first_name":"Иван",
        "middle_name": "Иванович",
        "last_name":"Петров",
        "country":"BY",
        "city":"Минск",
        "address":"ул. Независимости, 1",
        "zip":"220000",
        "phone":"+375172000000"
    },
    "customer":{
        "email":"ivanpetrov@example.com",
        "ip":"127.0.0.7"
    },
    "payment":{
        "ref_id":null,
        "message":null,
        "status":"pending",
        "gateway_id":1
    },
    "erip":{
        "request_id":"00000001",
        "service_no":99999999,
        "account_number":"123",
        "transaction_id":"0000001",
        "service_info":["Оплата заказа 123"],
        "instruction": ["'Расчёт' ЕРИП-> Интернет-магазины/сервисы-> B -> bePaid.by"],
        "receipt":["Спасибо за оплату заказа 123"]
    }
  }
}

Пример ответа об ошибке

Если случается ошибка, то ответ будет следующего вида:

{
  "message": "Unknown 'erip' payment method",
  "errors": {
    "system": [
      "System error."
    ]
  }
}
Параметр Описание
message * обязательный
string
errors * обязательный
object
errors.{key} * обязательный
array

Получение данных о платеже

По uid платежа

Чтобы получить детали платежа по :uid платежа, отправьте GET запрос с авторизационными данными на https://api.bepaid.by/beyag/payments/:uid.

По order_id платежа

Чтобы получить детали платежа по :order_id платежа, отправьте GET запрос с авторизационными данными на https://api.bepaid.by/beyag/payments/?order_id=:order_id.

Удаление по uid платежа

Если по какой-то причине, вам необходимо отменить созданное платёжное требование, то требования в статусах pending или permanent доступны для удаления.

Для сохранения истории и поддержания целостности данных, реального удаления платежа не происходит.

Платеж переходит в статус deleted и не будет больше доступен для оплаты.

Для удаления платёжного требования отправьте DELETE запрос с авторизационными данными на https://api.bepaid.by/beyag/payments/:uid.