Покупатель выбрал рассрочку, нажал «Оплатить», но заказ завис в статусе «Ожидание». Ошибка в подписи HMAC-SHA256 — и банк отклоняет запрос, клиент уходит. Интеграция рассрочки «Халва» от Беларусбанка в 1С-Битрикс требует точной верификации подписей и корректной обработки обратных вызовов. Мы реализовали 15+ таких интеграций, поэтому гарантируем надёжную работу обработчика. Средняя экономия на разработке по сравнению с готовыми модулями — 20–30%, а конверсия растёт на 15–25%.
Почему интеграция с Халвой требует особого подхода?
Рассрочка «Халва» — не обычная оплата картой. Банк возвращает покупателя на сайт после подтверждения, а затем отдельным webhook сообщает результат. Если обработчик неверно обработает return_url или уведомление — заказ может зависнуть в статусе ожидания, а деньги не поступят. Кроме того, API требует подписи HMAC-SHA256 для всех запросов — ошибка в генерации подписи приведёт к отказу. Наша команда реализует все проверки и обрабатывает edge-case, включая частичные возвраты и таймауты.
Для подключения нужны merchant_id и API-токен, выдаваемые Беларусбанком после договора. Мы помогаем с заявкой и настройкой тестовой среды.
Как устроено API Беларусбанка?
Банк предоставляет REST API для создания платежей. Основные шаги:
- Магазин отправляет запрос на создание платёжной сессии
- Получает redirect_url — ссылку для перехода покупателя
- Покупатель подтверждает рассрочку в интерфейсе банка
- Банк возвращает покупателя на return_url магазина
- Банк отправляет webhook подтверждения на notification_url
Параметры для уточнения у банка при подключении: endpoint API, формат запросов (обычно REST/JSON), метод аутентификации (токен или сертификат), тестовая и боевая среды. Документация доступна на официальном сайте Беларусбанка.
Создание обработчика платежей
Создаём обработчик в /local/php_interface/include/sale_payment/halva_belarus/: Файл .description.php:
<?php $PAYSYSTEM_SORT = 150; $PAYSYSTEM_NAME = 'Халва (Беларусбанк, рассрочка)'; $PAYSYSTEM_IS_CASH = 'N'; Класс обработчика:
<?php class HalvaBelarusHandler extends \Bitrix\Sale\PaySystem\ServiceHandler { public function initiatePay( \Bitrix\Sale\Payment $payment, \Bitrix\Main\Request $request = null ) { $order = $payment->getOrder(); $installmentMonths = $this->getBusinessValue($payment, 'INSTALLMENT_MONTHS'); $sessionData = [ 'merchant_id' => $this->getBusinessValue($payment, 'MERCHANT_ID'), 'order_id' => $order->getId(), 'amount' => $payment->getSum(), 'currency' => 'BYN', 'installment' => (int)$installmentMonths, 'description' => 'Заказ #' . $order->getId(), 'return_url' => $this->getSuccessUrl($payment), 'cancel_url' => $this->getFailUrl($payment), 'notification_url' => $this->getNotificationUrl($payment), 'customer_name' => $order->getPropertyValueByCode('NAME'), 'customer_phone' => $order->getPropertyValueByCode('PHONE'), ]; $response = $this->callApi('POST', '/v1/payments/create', $sessionData); if (empty($response['redirect_url'])) { $this->createError('Ошибка создания платёжной сессии Халва'); return \Bitrix\Sale\PaySystem\ServiceResult::create()->setRedirectUrl('/'); } $this->savePaymentId($payment, $response['payment_id']); $result = new \Bitrix\Sale\PaySystem\ServiceResult(); $result->setPaymentUrl($response['redirect_url']); return $result; } } Обработка уведомлений и возвратов
Банк отправляет POST-запрос на notification_url при успешной оплате или отказе. Ключевой момент — верификация подписи. Если подпись неверна, запрос отклоняется. В обработчике мы сверяем payment_id с сохранённым значением, чтобы предотвратить подмену.
<?php public function processRequest( \Bitrix\Sale\Payment $payment, \Bitrix\Main\Request $request ): \Bitrix\Sale\PaySystem\ServiceResult { $result = new \Bitrix\Sale\PaySystem\ServiceResult(); if (!$this->verifySignature($request)) { $result->addError(new \Bitrix\Main\Error('Неверная подпись запроса')); return $result; } $status = $request->get('status'); $paymentId = $request->get('payment_id'); $savedPaymentId = $this->getPaymentIdFromStorage($payment); if ($paymentId !== $savedPaymentId) { $result->addError(new \Bitrix\Main\Error('Несоответствие payment_id')); return $result; } if ($status === 'SUCCESS' || $status === 'APPROVED') { $result->setOperationType(\Bitrix\Sale\PaySystem\ServiceResult::MONEY_COMING); $payment->setPaid('Y'); } elseif ($status === 'CANCEL' || $status === 'REJECTED') { $result->setOperationType(\Bitrix\Sale\PaySystem\ServiceResult::MONEY_COMING); } return $result; } Возвраты выполняются через отдельный API-метод. Мы автоматически синхронизируем статус заказа с банком — это исключает ручные операции и ошибки.
Настройка и проверка на сайте
Платёжная система регистрируется в Битрикс через Магазин → Настройки → Платёжные системы → Добавить. Параметры обработчика:
| Параметр | Описание |
|---|---|
| MERCHANT_ID | ID магазина в системе Беларусбанка |
| API_TOKEN | Токен авторизации |
| INSTALLMENT_MONTHS | Количество месяцев рассрочки (список: 3, 6, 12, 24) |
| TEST_MODE | Тестовый режим (Y/N) |
| API_URL | URL API (тест / боевой) |
Добавляем проверку минимальной суммы заказа:
<?php public function isAvailable(\Bitrix\Sale\PayableItemCollection $basket): bool { $total = $basket->getPrice(); $min = (float)\Bitrix\Main\Config\Option::get('halva_belarus', 'min_amount', 50); return $total >= $min; } Как мы тестируем интеграцию?
Тестирование проходит в песочнице банка с реальными тестовыми картами. Мы проверяем сценарии: успешная оплата, отказ, частичный возврат, таймаут. После подтверждения всех статусов обработчик переносится на боевую среду. Это исключает сюрпризы после запуска.
Что входит в услугу и за сколько дней мы её выполним?
- Аудит текущей платёжной системы и требований банка
- Разработка обработчика с верификацией подписей и обработкой ошибок
- Настройка тестовой и боевой среды API
- Интеграция webhook-уведомлений и обработка статусов
- Тестирование с реальными картами в песочнице банка
- Документация по эксплуатации и обучение вашего администратора
- Гарантийная поддержка в течение 30 дней после запуска
| Этап | Срок |
|---|---|
| Настройка тестового подключения к API банка | 1 день |
| Обработчик платёжной системы (initiatePay) | 2 дня |
| Обработчик уведомлений + верификация подписи | 2 дня |
| Возвраты через API | 1 день |
| Тестирование в тестовой среде банка | 2 дня |
| Итого | 8–10 дней |
Наш опыт и процесс
Мы работаем с 1С-Битрикс более 10 лет и выполнили 50+ интеграций с платёжными системами: Халва, ЮKassa, Сбер. Наши решения проходят аудит банка с первого раза. Процесс включает этапы: анализ требований → проектирование → реализация → тестирование → деплой. На каждом этапе вы получаете промежуточный результат и можете внести правки.
Сравните: кастомная разработка под ключ обходится дешевле и гибче, чем покупка готового модуля с ограниченным функционалом. Мы адаптируем обработчик под вашу архитектуру — будь то многосайтовость или нестандартный обмен с 1С.
Получите консультацию по интеграции — напишите нам. Мы оценим ваш проект и предложим оптимальное решение. Закажите интеграцию прямо сейчас и получите расширенную поддержку на месяц.