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

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

«Магнит» — программа рассрочки от Банка ВТБ (Беларусь). Один из распространённых инструментов потребительского кредитования на белорусском рынке. Покупатель оформляет рассрочку на 6–36 месяцев, магазин получает сумму от ВТБ. Интеграция с сайтом на Битрикс — стандартный обработчик платёжной системы с перенаправлением на страницу банка.

API ВТБ Беларусь для партнёров

ВТБ предоставляет REST API для интернет-магазинов. Авторизация — Basic Auth (логин/пароль партнёра) или OAuth 2.0, зависит от тарифа подключения. В запросе на подключение уточняйте: тип авторизации, тестовую среду, формат уведомлений.

Базовая схема:

1. Магазин отправляет POST /api/v1/credits/applications с данными заказа и клиента
2. ВТБ возвращает application_id и redirect_url
3. Клиент заполняет анкету в интерфейсе ВТБ
4. ВТБ отправляет webhook о решении
5. При одобрении — деньги переводятся магазину

Обработчик платёжной системы

class MagnitVtbHandler extends \Bitrix\Sale\PaySystem\ServiceHandler
{
    public function initiatePay(
        \Bitrix\Sale\Payment $payment,
        \Bitrix\Main\Request $request = null
    ) {
        $order = $payment->getOrder();

        // Доступные сроки рассрочки (месяцы)
        $availableTerms = array_map('intval', explode(',',
            $this->getBusinessValue($payment, 'AVAILABLE_TERMS') ?? '6,12,24,36'
        ));

        $payload = [
            'partnerOrderId' => 'BX-' . $order->getId(),
            'totalAmount'    => $payment->getSum(),
            'currency'       => 'BYN',
            'terms'          => $availableTerms,
            'goods'          => $this->buildGoodsList($order),
            'client'         => [
                'firstName'   => $order->getPropertyValueByCode('NAME'),
                'lastName'    => $order->getPropertyValueByCode('LAST_NAME'),
                'middleName'  => $order->getPropertyValueByCode('SECOND_NAME'),
                'mobilePhone' => $this->normalizePhone($order->getPropertyValueByCode('PHONE')),
                'email'       => $order->getPropertyValueByCode('EMAIL'),
            ],
            'urls' => [
                'success'  => $this->getSuccessUrl($payment),
                'fail'     => $this->getFailUrl($payment),
                'callback' => $this->getNotificationUrl($payment),
            ],
        ];

        $response = $this->sendRequest('POST', '/api/v1/credits/applications', $payload);

        if (empty($response['redirectUrl'])) {
            $this->setError('ВТБ Магнит: не получен redirectUrl');
            return \Bitrix\Sale\PaySystem\ServiceResult::create();
        }

        $this->saveApplicationId($payment->getField('ID'), $response['applicationId']);

        $result = new \Bitrix\Sale\PaySystem\ServiceResult();
        $result->setPaymentUrl($response['redirectUrl']);
        return $result;
    }

    private function buildGoodsList(\Bitrix\Sale\Order $order): array
    {
        $goods = [];
        foreach ($order->getBasket() as $item) {
            $goods[] = [
                'name'     => mb_substr($item->getField('NAME'), 0, 200),
                'price'    => round($item->getPrice(), 2),
                'quantity' => (int)$item->getQuantity(),
                'article'  => (string)$item->getProductId(),
                'brand'    => $item->getField('DETAIL_PAGE_URL'), // или из свойства товара
            ];
        }
        return $goods;
    }

    private function normalizePhone(string $phone): string
    {
        $digits = preg_replace('/\D/', '', $phone);
        // Белорусский формат: +375XXXXXXXXX
        if (strlen($digits) === 11 && $digits[0] === '8') {
            $digits = '375' . substr($digits, 1);
        }
        return '+' . ltrim($digits, '+');
    }
}

Webhook от ВТБ

ВТБ отправляет POST на callback_url при изменении статуса заявки. Верификация через HMAC-подпись или IP-whitelist (белый список IP ВТБ):

public function processRequest(\Bitrix\Sale\Payment $payment, \Bitrix\Main\Request $request)
{
    $allowedIps = ['194.XXX.XXX.0/24']; // IP-диапазон ВТБ Беларусь
    if (!$this->isAllowedIp($request->getServer()->get('REMOTE_ADDR'), $allowedIps)) {
        http_response_code(403);
        exit;
    }

    $data   = json_decode(file_get_contents('php://input'), true);
    $result = new \Bitrix\Sale\PaySystem\ServiceResult();

    switch ($data['status'] ?? '') {
        case 'APPROVED':
        case 'ISSUED':  // Кредит выдан, деньги у магазина
            $result->setOperationType(\Bitrix\Sale\PaySystem\ServiceResult::MONEY_COMING);
            $payment->setPaid('Y');
            break;
        case 'DECLINED':
            // Заявка отклонена — уведомляем клиента
            \Bitrix\Main\Mail\Event::send([
                'EVENT_NAME' => 'INSTALLMENT_DECLINED',
                'LID'        => SITE_ID,
                'C_FIELDS'   => ['ORDER_ID' => $payment->getOrderId()],
            ]);
            break;
    }

    http_response_code(200);
    echo json_encode(['status' => 'ok']);
    return $result;
}

Виджет «Рассчитать рассрочку» на сайте

На странице товара и в корзине показываем калькулятор ежемесячного платежа:

function calcMagnitInstallment(price) {
    const terms = [6, 12, 24, 36];
    const container = document.getElementById('magnit-installment');
    container.innerHTML = terms.map(t =>
        `<div class="term-option">
            <span>${t} мес.</span>
            <strong>${Math.ceil(price / t)} руб./мес.</strong>
        </div>`
    ).join('');
}

Сроки