Інтеграція 1С-Бітрікс з платіжною системою ЄРІП (Білорусь)

Інтеграція 1С-Бітрікс із платіжною системою ЄРИП (Білорусь)

ЄРИП (Єдиний розрахунковий і інформаційний простір) — національна платіжна інфраструктура Білорусі, через яку проводиться переважна більшість комунальних, державних і комерційних платежів. Для білоруського інтернет-магазину відсутність ЄРИП у списку способів оплати — помітна втрата конверсії: значна частина платежів у країні проходить саме через цю систему, а не через картковий еквайринг.

Як влаштований ЄРИП для інтернет-магазинів

На відміну від карткового еквайрингу, ЄРИП — це не «плати прямо зараз на сайті». Схема інша:

1. Магазин реєструє рахунок у системі ЄРИП через API свого банку-агента
2. Покупець отримує унікальний номер рахунку (або QR-код)
3. Покупець самостійно оплачує через будь-який банк, банкомат, термінал або застосунок, підключений до ЄРИП
4. Система надсилає нотифікацію в магазин про факт оплати

Прямого API у ЄРИП немає — взаємодія йде через банк-агент, у якого відкрито розрахунковий рахунок компанії. Кожен банк надає власний API або шлюз для виставлення рахунків у ЄРИП. Беларусбанк, Пріорбанк, Альфа-Банк, МТБанк — у кожного свій протокол, хоча базова логіка схожа.

Технічна інтеграція в Бітрікс

Оскільки єдиного API ЄРИП не існує, інтеграція будується як кастомний обробник платіжної системи модуля sale, адаптований під API конкретного банку.

Типова структура обробника в /local/php_interface/include/sale_payment/erip/:

handler.php         — логіка виставлення рахунку і перевірки статусу
.description.php    — метадані, назва, іконка ЄРИП
.settings.php       — bankApiUrl, merchantId, apiKey, serviceCode
template/           — відображення реквізитів для оплати покупцю

Ключові методи обробника:

• initiatePay — викликає API банку для реєстрації рахунку, отримує billId і eripQrCode, зберігає в полях платежу
• processRequest — обробляє webhook від банку при надходженні оплати
• checkPayment — активне опитування статусу (використовується як fallback, якщо webhook не надійшов)

Параметри виставлення рахунку

Типовий запит до API банку для реєстрації рахунку в ЄРИП:

{
  "merchantId": "YOUR_MERCHANT_ID",
  "serviceCode": "ERIP_SERVICE_CODE",
  "invoiceNumber": "ORD-12345",
  "amount": 125.50,
  "currency": "BYN",
  "description": "Оплата замовлення №12345",
  "expireAt": "2024-12-31T23:59:59",
  "callbackUrl": "https://yourshop.by/bitrix/tools/sale_ps_result.php",
  "returnUrl": "https://yourshop.by/personal/order/detail/12345/"
}

serviceCode — це код вашої послуги в дереві ЄРИП. Присвоюється при підключенні банком. Саме за ним покупець знаходить ваш магазин у меню ЄРИП («Інтернет-магазини → Категорія → Ваш магазин»).

Відображення реквізитів покупцю

Після виставлення рахунку покупцю потрібно показати:

• Номер рахунку в ЄРИП (або QR-код) для оплати вручну
• Інструкцію: «Інтернет-банкінг → ЄРИП → Пошук за номером» або шлях через дерево послуг
• Термін дії рахунку
• QR-код для швидкої оплати через мобільний банк

Шаблон template/ компонента платіжної системи відповідає за цей екран. Стандартна сторінка «дякуємо за замовлення» в Бітрікс тут не підходить — потрібна сторінка очікування оплати з динамічним оновленням статусу через AJAX або WebSocket.

Обробка нотифікацій та підтвердження оплати

Банк надсилає POST-повідомлення на callbackUrl при надходженні платежу. Обробник повинен:

1. Верифікувати підпис запиту (кожен банк використовує свій метод — HMAC, RSA або перевірку IP-whitelist)
2. Знайти платіж за invoiceNumber або billId
3. Перевірити відповідність суми (покупець міг оплатити неповну суму)
4. Викликати $payment->setPaid('Y') тільки при повній оплаті
5. Оновити статус замовлення відповідно до бізнес-логіки магазину

Часткова оплата — специфіка ЄРИП. Система допускає оплату рахунку кількома транзакціями. Якщо це небажано, при реєстрації рахунку вказується прапор partialPaymentAllowed: false.

Реальний кейс: невідповідність суми

Білоруський магазин будматеріалів. Покупець оплатив рахунок у ЄРИП, але замовлення так і не підтвердилося — менеджери почали розбиратися через 2 години. Причина: покупець оплатив 124,50 BYN замість 125,50 BYN (помилився при ручному введенні суми). Система записала факт оплати, але обробник не підтвердив платіж через невідповідність суми. Рішення: додати автоматичне сповіщення менеджеру при «майже повній» оплаті (відхилення до 1% або 1 BYN) і надати інтерфейс ручного підтвердження в адміністративній частині.

Терміни та етапи

Реєстрація в дереві ЄРИП — найтриваліший етап, який не залежить від розробника. Починайте його паралельно з розробкою.