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

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

«Халва» в Беларуси — карта рассрочки Беларусбанка. Покупатель платит без процентов частями от 3 до 24 месяцев, магазин получает деньги сразу (за вычетом комиссии банка). Для подключения к сайту на Битрикс нужно реализовать обработчик платёжной системы, который инициирует оплату через API Беларусбанка и обрабатывает результат.

Техническая сторона Халва (Беларусбанк)

Беларусбанк предоставляет 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:

$PAYSYSTEM_SORT = 150;
$PAYSYSTEM_NAME = 'Халва (Беларусбанк, рассрочка)';
$PAYSYSTEM_IS_CASH = 'N';

Класс обработчика:

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 при успешной оплате или отказе:

public function processRequest(
    \Bitrix\Sale\Payment $payment,
    \Bitrix\Main\Request $request
): \Bitrix\Sale\PaySystem\ServiceResult {
    $result = new \Bitrix\Sale\PaySystem\ServiceResult();

    // Верификация подписи (метод зависит от банка: HMAC или RSA)
    if (!$this->verifySignature($request)) {
        $result->addError(new \Bitrix\Main\Error('Неверная подпись запроса'));
        return $result;
    }

    $status = $request->get('status');
    $paymentId = $request->get('payment_id');

    // Сверяем 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;
}

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

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

Ограничения по сумме заказа

Минимальная сумма для рассрочки Халва (Беларусбанк) — уточняется в договоре с банком. В обработчике добавляем проверку:

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;
}

Сроки