Інтеграція 1С-Бітрікс з розстрочкою Магніт (Білорусь)

Інтеграція 1С-Бітрікс з розстрочкою Магніт (Білорусь)

«Магніт» — програма розстрочки від Банку ВТБ (Білорусь). Один із поширених інструментів споживчого кредитування на білоруському ринку. Покупець оформлює розстрочку на 6–36 місяців, магазин отримує суму від ВТБ. Інтеграція з сайтом на 1С-Бітрікс — стандартний обробник платіжної системи з перенаправленням на сторінку банку.

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('');
}

Терміни