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

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

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

• иметь авторизацию типа Basic c ID магазина и секретным ключем магазина как имя пользователя и пароль соответственно;
• иметь заголовки Content-Type: application/json и Accept: application/json.

Запрос на оплату через ЕРИП отправляется в виде 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	Время создания платёжного требования.
manually_corrected_at	string	Время корректировки параметров транзакции службой технической поддержки, формат ISO-8601.
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",
    "manually_corrected_at": null,
    "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.