1C-Bitrix Integration with Magnit Installment (Belarus)

"Magnit" is an installment program from VTB Bank (Belarus). One of the common consumer credit tools on the Belarusian market. The buyer applies for installment for 6–36 months, the store receives the amount from VTB. Integration with a Bitrix site is a standard payment system handler with redirect to the bank page. We have implemented such integrations for 30+ projects and guarantee stable performance under load. The cost of integration is determined after analyzing your specific requirements.

What problems do we solve during integration?

Common issues include incorrect handling of application statuses: the store doesn't receive a callback about approval, leaving the customer without confirmation. Another problem is phone number format mismatch: the VTB API expects +375, while the site stores 8-XXX or 375. Our implementation includes automatic number normalization. A third typical case is missing HMAC verification of webhooks, leading to false triggers. We eliminate all these errors at the design stage.

How we do it

We use the standard class \Bitrix\Sale\PaySystem\ServiceHandler. Authorization in VTB API is Basic Auth or OAuth 2.0. We send partnerOrderId with the prefix BX- for uniqueness. We configure tagged caching for the installment calculator. Our implementation is faster and more reliable than a custom one. Implementation details are below.

VTB Belarus API for Partners

VTB provides a REST API for online stores. Authorization is Basic Auth (partner login/password) or OAuth 2.0, depending on the connection tariff. When requesting connection, specify: authorization type, test environment, notification format. Official API documentation can be reviewed on the VTB portal. VTB Belarus. Partner API: https://www.vtb.by/partner

Basic scheme:

1. Store sends POST /api/v1/credits/applications with order and customer data
2. VTB returns application_id and redirect_url
3. Customer fills out the application in VTB interface
4. VTB sends a webhook with the decision
5. If approved, money is transferred to the store

Payment System Handler

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 from VTB

VTB sends POST to callback_url when the application status changes. Verification via HMAC signature or IP whitelist (VTB IP range):

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

Installment Calculator Widget on the Site

On the product page and cart, we show a calculator for the monthly payment. Clicking a term opens the application form.

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

How Integration Affects Conversion

Installment lowers the entry barrier for customers with high cart totals. According to our data, the average order value increases by 30–50%, and conversion to checkout by 15–25%. Customers who couldn't pay upfront become buyers. Meanwhile, the store receives the full amount minus the bank's commission, with no risk of late payments.

Why Choose Our Integration

We don't just connect the API. We check corner cases: partial returns, order cancellations, status changes during delays. The handler correctly saves the application_id in the payment so you can always track the application. The code is covered by tests, and webhooks are protected from forgery.

Timeline

What’s Included

Our team consists of Bitrix-certified specialists with over 5 years of experience. We guarantee correct operation of the handler and webhooks. We will assess your project and offer the optimal solution. Contact us for a consultation and receive an individual integration plan. Order integration today.