Інтеграція 1С-Бітрікс з розстрочкою Магніт (Білорусь)
«Магніт» — програма розстрочки від Банку ВТБ (Білорусь). Один з поширених інструментів споживчого кредитування на білоруському ринку. Покупець оформлює розстрочку на 6–36 місяців, магазин отримує суму від ВТБ. Інтеграція з сайтом на Бітрікс — стандартний обробник платіжної системи з перенаправленням на сторінку банку. Ми реалізували такі інтеграції для 30+ проектів і гарантуємо стабільну роботу під навантаженням.
З якими проблемами стикаються при інтеграції?
Часто зустрічається невірна обробка статусів заявки: магазин не отримує callback про схвалення, і клієнт залишається без підтвердження. Інша проблема — несумісність формату телефону: API ВТБ очікує +375, а сайт зберігає 8-XXX або 375. Наша реалізація включає автоматичну нормалізацію номера. Третій типовий кейс — відсутність HMAC-верифікації вебхуків, що призводить до хибних спрацювань. Всі ці помилки ми усуваємо на етапі проектування.
Як ми це робимо?
Використовуємо стандартний клас \Bitrix\Sale\PaySystem\ServiceHandler. Авторизація в API ВТБ — Basic Auth або OAuth 2.0. У запиті передаємо partnerOrderId з префіксом BX- для унікальності. Налаштовуємо теговане кешування для калькулятора розстрочки. Наша реалізація швидша та надійніша за саморобну. Деталі реалізації — нижче.
API ВТБ Білорусь для партнерів
ВТБ надає REST API для інтернет-магазинів. Авторизація — Basic Auth (логін/пароль партнера) або OAuth 2.0, залежить від тарифу підключення. У запиті на підключення уточнюйте: тип авторизації, тестове середовище, формат сповіщень. Офіційну документацію API можна вивчити на порталі ВТБ. ВТБ Білорусь. Партнерський API: https://www.vtb.by/partner
Базова схема:
- Магазин відправляє
POST /api/v1/credits/applicationsз даними замовлення та клієнта - ВТБ повертає
application_idіredirect_url - Клієнт заповнює анкету в інтерфейсі ВТБ
- ВТБ відправляє webhook про рішення
- При схваленні — гроші переводяться магазину
Обробник платіжної системи
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('');
}
Як інтеграція впливає на конверсію?
Розстрочка знижує поріг входу для клієнтів з високою сумою кошика. За нашими даними, середній чек зростає на 30–50%, а конверсія в оформлення — на 15–25%. Клієнти, які не могли оплатити одразу, стають покупцями. При цьому магазин отримує всю суму за вирахуванням комісії банку, без ризику прострочень.
Чому варто обрати нашу інтеграцію?
Ми не просто підключаємо API. Ми перевіряємо корнер-кейси: часткові повернення, скасування замовлень, зміну статусів при затримках. Обробник коректно зберігає application_id в платіж, щоб ви завжди могли відстежити заявку. Код покритий тестами, а вебхуки захищені від підробок.
Процес роботи: від запиту до деплою
| Етап | Зміст | Термін |
|---|---|---|
| Аналітика | Вивчення API ВТБ, схеми даних, вимог | 1 день |
| Проектування | Розробка архітектури обробника та віджета | 1 день |
| Реалізація | Написання коду, модульне тестування | 3–4 дні |
| Інтеграція | Налаштування тестового середовища, пробні платежі | 1–2 дні |
| Деплой | Викатка на бой, моніторинг роботи | 1 день |
| Підтримка | Виправлення помилок, консультації 30 днів | — |
Терміни
| Етап | Термін |
|---|---|
| Налаштування API-підключення та тестового середовища | 1 день |
| Обробник платіжної системи | 2–3 дні |
| Webhook та обробка статусів | 1–2 дні |
| Повернення через API | 1 день |
| Віджет калькулятора розстрочки | 0.5 дня |
| Тестування | 2 дні |
| Разом | 8–10 днів |
Що входить в роботу
| Деліверабли | Опис |
|---|---|
| Документація по API | Схема запитів, приклади відповідей, опис обробки помилок |
| Доступи та конфігурація | Налаштування тестового та бойового середовищ ВТБ, генерація токенів |
| Вихідний код обробника | PHP-клас з коментарями, готовий до встановлення в Бітрікс |
| Інструкція з налаштування | Покрокове керівництво для системного адміністратора |
| Навчання менеджерів | Як відповідати на запитання клієнтів, перевіряти статуси |
| Підтримка 30 днів | Виправлення помилок, консультації по доробкам |
Наша команда — сертифіковані спеціалісти по Бітрікс з досвідом 5+ років. Гарантуємо коректну роботу обробника та вебхуків. Оцінимо ваш проект і запропонуємо оптимальне рішення. Зв'яжіться з нами для консультації — отримайте індивідуальний план інтеграції.