Інтеграція 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;
}

Терміни