Інтеграція 1С-Бітрікс з платіжною системою Розрахунок (ЄРІР) (Білорусь)
«Розрахунок» — це торговельне найменування системи ЄРІР, що використовується в контексті роздрібних платежів. Частина банків та платіжних сервісів Білорусі надає доступ до ЄРІР саме під брендом «Розрахунок», і для розробника важливо розуміти: на технічному рівні це той самий ЄРІР (Єдиний розрахунковий і інформаційний простір), просто з іншою точкою входу та API від конкретного банку-агента. Плутанина в термінології часто призводить до того, що один магазин підключає «Розрахунок» і «ЄРІР» як два різних способи оплати, хоча вони ведуть в одну інфраструктуру.
Принципова відмінність від інших платіжних систем
ЄРІР/Розрахунок — це не картковий шлюз. Покупець не вводить дані картки на сайті. Натомість:
- Магазин виставляє рахунок у ЄРІР через API банку
- Покупець отримує унікальний номер (код) рахунку
- Оплачує через будь-який банк, підключений до ЄРІР: Беларусбанк, Пріорбанк, Альфа-Банк, МТБанк, БелВЭБ та інші — через інтернет-банкінг, мобільний банк, банкомат або касу
- Інформація про оплату надходить до магазину через webhook
Ключовий момент: сервіс «Розрахунок» передбачає, що покупець знаходить ваш магазин у дереві послуг ЄРІР. Для цього у компанії має бути зареєстрований код послуги в дереві ЄРІР. Без цього коду система виставлених рахунків не працюватиме.
Підключення через банк-агент
Прямого API у ЄРІР/Розрахунок немає. Взаємодія відбувається через банк, у якому відкрито розрахунковий рахунок компанії. Кожен банк надає свій протокол:
| Банк | Протокол | Особливості |
|---|---|---|
| Беларусбанк | SOAP/XML | Детальна документація |
| Пріорбанк | REST JSON | Сучасний API |
| МТБанк | REST JSON | Швидкий onboarding |
| Альфа-Банк | REST JSON | Підтримка QR |
| БелВЭБ | REST/XML | Корпоративні клієнти |
При розробці обробника для Бітрікс вибір протоколу визначається банком клієнта. Якщо планується зміна банку — обробник доведеться адаптувати.
Реалізація в Бітрікс
Розташування: /local/php_interface/include/sale_payment/raschyot_erip/
Базова логіка initiatePay (на прикладі REST-протоколу):
public function initiatePay($payment, $request = null)
{
$order = $payment->getOrder();
$billData = [
'merchantId' => $this->getParam('MERCHANT_ID'),
'serviceCode' => $this->getParam('SERVICE_CODE'),
'invoiceNo' => $order->getField('ACCOUNT_NUMBER'),
'amount' => $payment->getSum(),
'currency' => 'BYN',
'description' => 'Замовлення ' . $order->getField('ACCOUNT_NUMBER'),
'expireDate' => date('Y-m-d', strtotime('+3 days')),
'callbackUrl' => $this->getCallbackUrl(),
];
$response = $this->sendRequest('POST', '/invoices', $billData);
if ($response['status'] === 'created') {
$payment->setField('PAY_SYSTEM_ID_EXTERNAL', $response['invoiceId']);
$this->showEripRequisites($response['invoiceId'], $response['eripCode']);
}
}
Відображення реквізитів ЄРІР
Покупцю потрібно показати чітку інструкцію. Різні сегменти аудиторії використовують різні канали:
- Інтернет-банкінг: ЄРІР → Пошук → Ввести код рахунку або знайти через дерево послуг
- Мобільний застосунок: QR-сканування
- Банкомат/інфокіоск: ЄРІР → ваша послуга → ввести номер замовлення
- Каса банку: назвати касиру код послуги та номер замовлення
Шаблон платіжної системи в Бітрікс повинен показувати всі варіанти, а не лише один — це знижує кількість звернень до підтримки.
Статуси та логіка підтвердження
Можливі статуси рахунку в ЄРІР:
| Статус | Значення | Дія в Бітрікс |
|---|---|---|
CREATED |
Рахунок виставлено | Очікувати |
PAID |
Оплачено | $payment->setPaid('Y') |
PART_PAID |
Частково оплачено | Повідомити менеджера |
EXPIRED |
Термін вийшов | Скасувати або продовжити |
CANCELLED |
Скасовано магазином | Оновити статус |
Часткова оплата в ЄРІР допустима за замовчуванням — якщо її не потрібно приймати, явно вказати в запиті створення рахунку (partialPayment: false).
Подвійна реєстрація: типова помилка
Магазин створює рахунок у ЄРІР, покупець не платить. Покупець повертається, натискає «Оплатити знову» — магазин створює другий рахунок. Тепер два активних рахунки на одне замовлення. Покупець оплачує один, другий залишається активним. Через три дні обидва закінчуються — і база засмічується.
Рішення: перед створенням рахунку перевіряти, чи немає вже активного рахунку за цим замовленням (зберігати invoiceId у полях платежу b_sale_payment). Якщо є — показувати його реквізити, а не створювати новий.
Реальний кейс: реєстрація в дереві ЄРІР
Мінський роздрібний магазин побутової хімії. Технічна інтеграція зайняла 3 дні, але запуск затримався на 3 тижні — компанія не знала, що реєстрація коду послуги в дереві ЄРІР є окремим адміністративним процесом через банк і НКФО «Розрахунок». Документи, погодження, тестування дерева. Рекомендація: починати реєстрацію в ЄРІР паралельно з розробкою, а не після неї.