Интеграция 1С-Битрикс с рассрочкой Халва (Беларусь)

Покупатель выбрал рассрочку, нажал «Оплатить», но заказ завис в статусе «Ожидание». Ошибка в подписи HMAC-SHA256 — и банк отклоняет запрос, клиент уходит. Интеграция рассрочки «Халва» от Беларусбанка в 1С-Битрикс требует точной верификации подписей и корректной обработки обратных вызовов. Мы реализовали 15+ таких интеграций, поэтому гарантируем надёжную работу обработчика. Средняя экономия на разработке по сравнению с готовыми модулями — 20–30%, а конверсия растёт на 15–25%.

Почему интеграция с Халвой требует особого подхода?

Рассрочка «Халва» — не обычная оплата картой. Банк возвращает покупателя на сайт после подтверждения, а затем отдельным webhook сообщает результат. Если обработчик неверно обработает return_url или уведомление — заказ может зависнуть в статусе ожидания, а деньги не поступят. Кроме того, API требует подписи HMAC-SHA256 для всех запросов — ошибка в генерации подписи приведёт к отказу. Наша команда реализует все проверки и обрабатывает edge-case, включая частичные возвраты и таймауты.

Для подключения нужны merchant_id и API-токен, выдаваемые Беларусбанком после договора. Мы помогаем с заявкой и настройкой тестовой среды.

Как устроено API Беларусбанка?

Банк предоставляет REST API для создания платежей. Основные шаги:

1. Магазин отправляет запрос на создание платёжной сессии
2. Получает redirect_url — ссылку для перехода покупателя
3. Покупатель подтверждает рассрочку в интерфейсе банка
4. Банк возвращает покупателя на return_url магазина
5. Банк отправляет 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-метод. Мы автоматически синхронизируем статус заказа с банком — это исключает ручные операции и ошибки.

Настройка и проверка на сайте

Платёжная система регистрируется в Битрикс через Магазин → Настройки → Платёжные системы → Добавить. Параметры обработчика:

Добавляем проверку минимальной суммы заказа:

<?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 дней после запуска

Наш опыт и процесс

Мы работаем с 1С-Битрикс более 10 лет и выполнили 50+ интеграций с платёжными системами: Халва, ЮKassa, Сбер. Наши решения проходят аудит банка с первого раза. Процесс включает этапы: анализ требований → проектирование → реализация → тестирование → деплой. На каждом этапе вы получаете промежуточный результат и можете внести правки.

Сравните: кастомная разработка под ключ обходится дешевле и гибче, чем покупка готового модуля с ограниченным функционалом. Мы адаптируем обработчик под вашу архитектуру — будь то многосайтовость или нестандартный обмен с 1С.

Получите консультацию по интеграции — напишите нам. Мы оценим ваш проект и предложим оптимальное решение. Закажите интеграцию прямо сейчас и получите расширенную поддержку на месяц.