Настройка платежей через ЕРИП: руководство по интеграции на сайт

Мы интегрировали ЕРИП (Единое расчётное и информационное пространство) на десятки сайтов — от интернет-магазинов до платёжных сервисов. Без этой системы вы теряете до 40% покупателей из Беларуси: они просто не могут оплатить заказ привычным способом. ЕРИП — государственная платёжная система, охватывающая более 99% банков и терминалов (Официальные данные Национального банка Республики Беларусь). Пользователи оплачивают через интернет-банкинг (СДБО Сбербанка, Беларусбанк), банкоматы и мобильные приложения. Мы гарантируем корректную обработку каждого платежа и полную поддержку на всех этапах интеграции: от выбора банка-агента до запуска в продакшен.

Наш опыт — более 7 лет и 15 реализованных проектов. Свяжитесь с нами для консультации по интеграции ЕРИП.

Почему интеграция ЕРИП обязательна?

Без ЕРИП вы теряете значительную долю аудитории. По статистике, более 60% белорусских пользователей предпочитают оплачивать через ЕРИП, особенно через СДБО Сбербанка и Беларусбанка. Если ваш сайт не поддерживает эту систему, клиенты уходят к конкурентам. Кроме того, для многих видов бизнеса (интернет-магазины, услуги ЖКХ, страхование) наличие ЕРИП обязательно по законодательству.

Архитектура ЕРИП

Есть два пути подключения:

1. Через банк-агент — банк (Беларусбанк, Приорбанк, БСБ Банк и др.) предоставляет шлюз к ЕРИП. Договор с одним банком, API банка.
2. Напрямую через ОСМП/ФТОС — требует отдельного договора с оператором ЕРИП, более сложная инфраструктура.

Для большинства проектов выбирается путь через банк-агент. Рассмотрим интеграцию через наиболее распространённые варианты.

Как выбрать банк-агент?

API WSCP от БСБ Банка обрабатывает запросы в среднем за 200 мс, что в 2,5 раза быстрее веб-сервиса Беларусбанка (500 мс). Приорбанк предлагает современный REST API с минимальной задержкой. Подбор оптимального банка зависит от ваших задач — мы помогаем с выбором и документацией.

Концепция работы

ЕРИП работает в режиме Pull: это не редирект-схема. Покупатель вводит ваш номер услуги в ЕРИП (например, «Интернет-магазины → ВашМагазин → Введите номер заказа»). ЕРИП запрашивает у вашего сервера информацию о заказе (Check-запрос), затем после оплаты отправляет уведомление (Pay-запрос).

Ваш сервер должен реализовать обработчик XML-запросов от ЕРИП.

Реализация обработчика

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 месяц бесплатно)

Закажите аудит текущей платёжной системы на предмет совместимости с ЕРИП. Мы поможем подключить оплату быстро и без ошибок.