Интеграция 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) и предоставить интерфейс ручного подтверждения в административной части.

Сроки и этапы

Регистрация в дереве ЕРИП — самый долгий этап, не зависящий от разработчика. Начинайте его параллельно с разработкой.