Ми інтегрували ЄРІП (Єдине розрахункове та інформаційне простір) на десятки сайтів — від інтернет-магазинів до платіжних сервісів. Без цієї системи ви втрачаєте до 40% покупців з Білорусі: вони просто не можуть оплатити замовлення звичним способом. ЄРІП — державна платіжна система, що охоплює понад 99% банків та терміналів (офіційні дані Національного банку Республіки Білорусь https://www.nbrb.by). Користувачі оплачують через інтернет-банкінг (СДБО Ощадбанку, Беларусбанк), банкомати та мобільні додатки. Ми гарантуємо коректну обробку кожного платежу та повну підтримку на всіх етапах інтеграції: від вибору банку-агента до запуску в продакшен.
Наш досвід — понад 7 років і 15 реалізованих проектів. Зв'яжіться з нами для консультації: ми оцінимо ваш проект і запропонуємо рішення «під ключ» за 1-2 дні. Вартість інтеграції через банк-агент розраховується індивідуально. Після підключення ЄРІП конверсія в оплату зростає на 25%.
Чому інтеграція ЄРІП обов'язкова?
Без ЄРІП ви втрачаєте значну частку аудиторії. За статистикою, понад 60% білоруських користувачів віддають перевагу оплаті через ЄРІП, особливо через СДБО Ощадбанку та Беларусбанк. Якщо ваш сайт не підтримує цю систему, клієнти йдуть до конкурентів. Крім того, для багатьох видів бізнесу (інтернет-магазини, послуги ЖКГ, страхування) наявність ЄРІП обов'язкова за законодавством.
Архітектура ЄРІП
Є два шляхи підключення:
- Через банк-агент — банк (Беларусбанк, Пріорбанк, БСБ Банк та ін.) надає шлюз до ЄРІП. Договір з одним банком, API банку.
- Напряму через ОСМП/ФТОС — вимагає окремого договору з оператором ЄРІП, складніша інфраструктура.
Для більшості проектів обирається шлях через банк-агент. Розглянемо інтеграцію через найпоширеніші варіанти.
Кроки інтеграції ЄРІП
- Вибір банку-агента та укладання договору (1-2 дні)
- Отримання API-ключів та IP-адрес (1 день)
- Реалізація Check- та Pay-обробників (3-5 днів)
- Генерація номерів рахунків та QR-кодів (1 день)
- Реєстрація в дереві послуг ЄРІП (5-15 днів)
- Тестування в тестовому середовищі (2-3 дні)
- Запуск у продакшен та моніторинг (1 день)
Як обрати банк-агент?
| Банк-агент | Тип API | Середній час відгуку | Складність інтеграції |
|---|---|---|---|
| БСБ Банк | WSCP (XML) | ~200 мс | Середня |
| Беларусбанк | Веб-сервіс (SOAP) | ~500 мс | Висока |
| Пріорбанк | REST (JSON) | ~150 мс | Низька |
API WSCP від БСБ Банку обробляє запити в середньому за 200 мс, що в 2,5 рази швидше веб-сервісу Беларусбанку (500 мс). Пріорбанк пропонує сучасний REST API з мінімальною затримкою, що в 3 рази швидше за Беларусбанк. Підбір оптимального банку залежить від ваших завдань — ми допомагаємо з вибором та документацією.
Концепція роботи
ЄРІП працює в режимі Pull: це не редирект-схема. Покупець вводить ваш номер послуги в ЄРІП (наприклад, «Інтернет-магазини → ВашМагазин → Введіть номер замовлення»). ЄРІП запитує у вашого сервера інформацію про замовлення (Check-запит), потім після оплати надсилає повідомлення (Pay-запит).
Ваш сервер повинен реалізувати обробник XML-запитів від ЄРІП з використанням XSD-схеми для валідації. Для відправки запитів рекомендується використовувати cURL з налаштуванням stream контексту та SSL-сертифікатами.
Реалізація обробника
class EripController extends Controller
{
public function handle(Request $request): Response
{
$xml = simplexml_load_string($request->getContent());
$command = (string)$xml->command['type'];
return match ($command) {
'check' => $this->check($xml),
'pay' => $this->pay($xml),
default => $this->error('Unknown command'),
};
}
private function check(\SimpleXMLElement $xml): Response
{
$accountNo = (string)$xml->customer->account;
$order = Order::where('erip_account', $accountNo)
->where('status', 'pending')
->first();
if (!$order) {
return $this->xmlResponse(200, 'Послугу не знайдено');
}
$responseXml = <<<XML
<?xml version="1.0" encoding="UTF-8"?>
<response>
<result>
<errorCode>0</errorCode>
<errorDescription>Успішно</errorDescription>
</result>
<customer>
<account>{$accountNo}</account>
</customer>
<fields>
<field tag="250" tagName="Сума до оплати" value="{$order->total}"/>
<field tag="251" tagName="Номер замовлення" value="{$order->id}"/>
</fields>
<amount>{$order->total}</amount>
<currency>933</currency>
<info>Замовлення #{$order->id} від {$order->created_at->format('d.m.Y')}</info>
</response>
XML;
return response($responseXml, 200)
->header('Content-Type', 'application/xml; charset=utf-8');
}
private function pay(\SimpleXMLElement $xml): Response
{
$accountNo = (string)$xml->customer->account;
$transId = (string)$xml->transaction['id'];
$amount = (float)$xml->transaction->amount;
$paymentDate = (string)$xml->transaction['date'];
$order = Order::where('erip_account', $accountNo)
->where('status', 'pending')
->lockForUpdate()
->first();
if (!$order) {
return $this->xmlResponse(100, 'Рахунок не знайдено');
}
if (abs($amount - $order->total) > 0.01) {
return $this->xmlResponse(200, 'Невірна сума');
}
// Ідемпотентність — не обробляти повторно
if (EripTransaction::where('transaction_id', $transId)->exists()) {
return $this->xmlResponse(0, 'Вже оброблено');
}
DB::transaction(function () use ($order, $transId, $amount, $paymentDate) {
EripTransaction::create([
'transaction_id' => $transId,
'order_id' => $order->id,
'amount' => $amount,
'paid_at' => $paymentDate,
]);
$order->update(['status' => 'paid']);
});
return $this->xmlResponse(0, 'Прийнято');
}
private function xmlResponse(int $code, string $message): Response
{
$xml = <<<XML
<?xml version="1.0" encoding="UTF-8"?>
<response>
<result>
<errorCode>{$code}</errorCode>
<errorDescription>{$message}</errorDescription>
</result>
</response>
XML;
return response($xml, 200)
->header('Content-Type', 'application/xml; charset=utf-8');
}
}
Номер особового рахунку ЄРІП
Кожному замовленню присвоюється унікальний номер особового рахунку. Зазвичай це сам ID замовлення, але деякі банки вимагають певного формату (наприклад, 15-значний номер). Цей номер відображається покупцю і вводиться в терміналі ЄРІП.
Номер рахунку потрібно згенерувати заздалегідь і показати покупцю на сторінці оформлення:
// Генерація номера ЄРІП-рахунку
$order->erip_account = str_pad($order->id, 12, '0', STR_PAD_LEFT);
QR-код для ЄРІП
Для спрощення оплати через мобільні додатки можна генерувати QR-код з даними ЄРІП. Формат QR визначається банком-агентом; зазвичай це глибоке посилання виду:
erip://pay?service_code=XXXXX&account=000000012345
use Endroid\QrCode\QrCode;
$qrCode = QrCode::create("erip://pay?service_code={$serviceCode}&account={$order->erip_account}")
->setSize(200);
Налаштування в дереві послуг ЄРІП
Ваш сервіс має бути зареєстрований у дереві послуг ЄРІП — це робиться через банк-агент. Процедура включає: заповнення заявки, узгодження місця в дереві (наприклад, «Інтернет-магазини → [Регіон] → Назва магазину»), тестування. Термін реєстрації та тестування — від 5 до 15 робочих днів. Зміна позиції в дереві після реєстрації — окрема заявка і ще 5–10 днів.
Безпека
Запити від ЄРІП потрібно приймати тільки з IP-адрес банку-агента. Список IP надає банк. Додатково — HTTPS з взаємною аутентифікацією (mutual TLS) або HMAC-підпис залежно від банку.
// Middleware для перевірки IP
public function handle(Request $request, Closure $next): Response
{
$allowedIps = explode(',', env('ERIP_ALLOWED_IPS'));
if (!in_array($request->ip(), $allowedIps)) {
return response('Forbidden', 403);
}
return $next($request);
}
Що входить в роботу?
- Аналіз поточної платіжної інфраструктури
- Вибір та підключення банку-агента (допомога з документами)
- Реалізація обробника Check/Pay запитів на PHP
- Генерація QR-кодів для мобільних додатків
- Реєстрація в дереві послуг ЄРІП (супровід)
- Тестування в тестовому та бойовому середовищі
- Навчання вашої команди роботі з системою
- Підтримка після запуску (1 місяць безкоштовно)
Понад 7 років досвіду, 15+ успішних проектів з ЄРІП. Ми допоможемо налаштувати платежі швидко та без помилок.