Інтеграція 1С-Бітрікс з інтернет-еквайрингом Беларусбанк
Беларусбанк — найбільший державний банк Білорусі, через еквайринг якого проходить значна частина безготівкових платежів у країні. Інтернет-еквайринг Беларусбанку включає прийом карток Visa, Mastercard та Белкарт, а також виставлення рахунків у ЄРІР — все через єдиний шлюз. Для магазинів, рахунок яких відкрито в Беларусбанку, це нерідко найпростіше рішення: один банк, один договір, один шлюз.
Структура API Беларусбанку
Беларусбанк використовує для інтернет-еквайрингу шлюз на основі SOAP/XML-протоколу (стара версія) та REST API (нова версія, рекомендується для нових інтеграцій). REST API працює через https://payment.belarusbank.by/api/.
Основні методи REST API:
-
POST /payment/create— створення платіжної сесії -
GET /payment/status/{paymentId}— статус транзакції -
POST /payment/confirm— підтвердження при двохстадійній оплаті -
POST /payment/refund— повернення коштів -
POST /erip/invoice/create— створення рахунку в ЄРІР
Авторизація через Bearer-токен, що отримується запитом до /auth/token з client_id та client_secret.
Інтеграція з Бітрікс
Реалізується як кастомний обробник у /local/php_interface/include/sale_payment/belarusbank_acquiring/. Офіційного модуля на Маркетплейсі Бітрікс немає.
Запит на створення платежу:
{
"merchantId": "YOUR_MERCHANT_ID",
"orderId": "BXORDER_23456",
"amount": 23400,
"currency": "BYN",
"description": "Оплата замовлення №23456",
"returnUrl": "https://shop.by/thank-you/?id=23456",
"failUrl": "https://shop.by/payment-fail/?id=23456",
"notifyUrl": "https://shop.by/bitrix/tools/sale_ps_result.php",
"language": "ru",
"paymentMethod": "CARD"
}
Для ЄРІР paymentMethod змінюється на ERIP, і у відповіді повертаються реквізити рахунку замість URL платіжної сторінки.
Картки Белкарт: обов'язкова підтримка
Інтернет-еквайринг Беларусбанку включає процесинг карток Белкарт — національної платіжної системи Білорусі. Картки Белкарт широко використовуються зарплатними клієнтами державних підприємств. При підключенні еквайрингу Беларусбанку підтримка Белкарт вмикається автоматично — жодних додаткових налаштувань не потрібно, але важливо протестувати оплату тестовою карткою Белкарт, а не лише Visa/Mastercard.
3D-Secure та відмови
Беларусбанк вимагає 3D-Secure для всіх карткових транзакцій. При проходженні 3DS покупець перенаправляється на сторінку підтвердження банку-емітента. У Бітрікс це прозоро — все відбувається на стороні платіжної сторінки шлюзу. Але логи потрібно аналізувати за errorCode з відповіді payment/status:
| Код | Опис | Типова причина |
|---|---|---|
0000 |
Успішно | — |
0001 |
Відмова банку | Недостатньо коштів, блокування картки |
0005 |
Відмова системи | 3DS-помилка або таймаут |
0012 |
Недійсна транзакція | Картка не підтримує онлайн-оплату |
0051 |
Недостатньо коштів | — |
Обробка нотифікацій
Беларусбанк надсилає POST-сповіщення на notifyUrl. Тіло сповіщення:
{
"paymentId": "bb_pay_789012",
"orderId": "BXORDER_23456",
"status": "PAID",
"amount": 23400,
"currency": "BYN",
"timestamp": "2024-12-20T11:45:22+03:00",
"signature": "sha256_signature"
}
Верифікація підпису — HMAC-SHA256 від paymentId + orderId + amount + currency + secret. Після успішної верифікації та статусу PAID — $payment->setPaid('Y').
Повернення коштів
API підтримує як повне, так і часткове повернення через POST /payment/refund:
{
"paymentId": "bb_pay_789012",
"amount": 11700,
"reason": "Часткове повернення за домовленістю"
}
В адміністративній частині Бітрікс повернення можна реалізувати як кнопку на сторінці замовлення з викликом ProcessRequestRefund. Беларусбанк обробляє повернення протягом 1–3 робочих днів.
Реальний кейс: SOAP vs REST
Білоруський інтернет-магазин спортивних товарів працював на старій SOAP-інтеграції з Беларусбанком. Коли банк оновив сервіс, SOAP-шлюз почав повертати помилки Service Unavailable у періоди пікового навантаження. Аналіз показав: старий шлюз увійшов у режим обмеженої підтримки, новий REST API стабільніший. Міграція з SOAP на REST-обробник зайняла 3 робочі дні — включаючи рефакторинг парсингу відповідей та адаптацію логіки обробки нотифікацій.
Терміни
Укладення договору з Беларусбанком на інтернет-еквайринг — від 5 до 15 робочих днів. Розробка та тестування обробника — 2–4 робочі дні. Беларусбанк надає тестове середовище з тестовими картками одразу після підписання тестової угоди.