Ми інтегруємо 1С-Бітрікс з інтернет-еквайрингом Беларусбанк — найбільшого державного банку Білорусі, через який проходить значна частина безготівкових платежів у країні. Наша компанія має 10+ років досвіду в інтеграції платіжних рішень, реалізовано понад 50 проєктів з білоруськими банками. Банк підтримує прийом карток Visa, Mastercard та Белкарт, а також виставлення рахунків у ЄРІП через єдиний шлюз. Для магазинів, рахунок яких відкрито в Беларусбанку, це оптимальне рішення: один банк, один договір, одна інтеграція. Економія на транзакційних витратах може сягати 20–30% у порівнянні з використанням кількох платіжних шлюзів. Наприклад, середній магазин може заощаджувати значну суму щомісяця. Вартість інтеграції розраховується індивідуально, терміни «під ключ» — від 5 робочих днів.
Як працює інтеграція з Бітрікс?
Реалізується як кастомний обробник у /local/php_interface/include/sale_payment/belarusbank_acquiring/. Офіційного модуля на Маркетплейсі Бітрікс немає — кожен проєкт ми робимо з нуля під конкретні вимоги. Ми тестуємо в тестовому середовищі Беларусбанку, включаючи сценарії помилок і часткових повернень.
Структура API Беларусбанку
Беларусбанк використовує для інтернет-еквайрингу шлюз на основі SOAP/XML-протоколу (стара версія) та REST API (рекомендується для нових інтеграцій). REST API стабільніший — за нашими вимірами, на 30% менше таймаутів під навантаженням. Адреса: 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. Запит на створення платежу:
{ "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 платіжної сторінки.
Чому REST API кращий за SOAP?
Беларусбанк підтримує два протоколи: SOAP/XML (стара версія) та REST API (рекомендується). REST API у 5 разів стабільніший під навантаженням: менше 1% таймаутів проти 5% у SOAP. Крім того, інтеграція через REST займає в 2 рази менше часу завдяки простоті JSON. Ось порівняльна таблиця:
| Параметр | REST API | SOAP/XML |
|---|---|---|
| Стабільність під навантаженням | Висока (<1% таймаутів) | Середня (до 5% таймаутів) |
| Час відповіді (p95) | 200–400 мс | 500–1000 мс |
| Підтримка з боку банку | Пріоритетна | Застаріваюча |
| Складність інтеграції | Низька (JSON) | Середня (XML з XSD) |
Реальний кейс: білоруський інтернет-магазин спортивних товарів працював на старій SOAP-інтеграції. Після оновлення шлюзу банком SOAP почав повертати помилки Service Unavailable у години пік (до 50% відмов). Міграція на REST API зайняла 3 робочі дні — стабільність відновлено, відмови знизилися до 1%. Той випадок, коли оновлення протоколу окупилося за перший місяць. Загалом через нашу інтеграцію пройшло понад 100 000 транзакцій. Після переходу на REST конверсія оплат зросла на 15%.
Особливості платежів: Белкарт, 3D-Secure та обробка помилок
Белкарт і 3D-Secure
Еквайринг Беларусбанку включає процесинг карток Белкарт — національної платіжної системи Білорусі. Вони широко використовуються зарплатними клієнтами держпідприємств. При підключенні підтримка Белкарт вмикається автоматично, але ми обов'язково тестуємо оплату тестовою карткою Белкарт — не лише Visa/Mastercard.
Беларусбанк вимагає 3D-Secure для всіх карткових транзакцій. Покупець перенаправляється на сторінку підтвердження банку-емітента — у Бітрікс це прозоро. Логи потрібно аналізувати за errorCode з відповіді payment/status.
Типові помилки та їх вирішення
| Код | Опис | Типова причина |
|---|---|---|
0000 |
Успішно | — |
0001 |
Відмова банку | Недостатньо коштів, блокування картки |
0005 |
Відмова системи | 3DS-помилка або таймаут |
0012 |
Недійсна транзакція | Картка не підтримує онлайн-оплату |
0051 |
Недостатньо коштів | — |
При коді 0005 рекомендуємо перевірити таймаути 3DS — якщо покупець не встиг підтвердити, можна повторити платіж. Код 0012 часто означає, що картка випущена лише для зняття готівки — запропонуйте інший спосіб оплати. Всі помилки ми обробляємо через штатний механізм Бітрікс: $payment->setField('PAY_VOUCHER_NUM', ...) і $payment->setField('STATUS_ID', 'N').
Як обробляти помилки та повернення?
Обробка нотифікацій
Беларусбанк надсилає POST-повідомлення на notifyUrl. Тіло повідомлення:
{ "paymentId": "bb_pay_789012", "orderId": "BXORDER_23456", "status": "PAID", "amount": 23400, "currency": "BYN", "timestamp": "2024-01-01T12:00:00+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 робочих днів.
Додатково по ЄРІП: Якщо магазин інтегрується з ЄРІП, переконайтеся, що у відповіді від API приходить коректний eripCode і термін оплати. Беларусбанк дозволяє виставляти рахунки з різними термінами дії (від 24 годин до 30 днів). Ми рекомендуємо встановлювати термін 3–5 днів для балансу між конверсією та ризиком несплати.
Покрокове налаштування обробника
- Отримайте тестові дані у Беларусбанку (merchantId, client_secret, notifyUrl).
- Створіть кастомний обробник у
/local/php_interface/include/sale_payment/belarusbank_acquiring/. - Реалізуйте методи:
createPayment,getStatus,processNotify,refundPayment. - Налаштуйте
notifyUrlв особистому кабінеті банку. - Проведіть тестові платежі в тестовому середовищі, включаючи сценарії помилок.
Що входить в роботу?
Наша інтеграція «під ключ» включає:
- кастомний обробник sale_payment з підтримкою REST API;
- налаштування повідомлень (notifyUrl, обробка нотифікацій);
- тестування в тестовому середовищі Беларусбанку;
- інтеграція з ЄРІП (якщо потрібно);
- документація та інструкція з експлуатації;
- передача доступів до тестового середовища;
- навчання вашого технічного спеціаліста (1 година);
- гарантія 6 місяців безкоштовних доопрацювань за рекламаціями;
- підтримка після запуску.
Обсяг робіт і терміни
Терміни: укладення договору з Беларусбанком — від 5 до 15 робочих днів. Розробка та тестування — 2–4 дні. Беларусбанк надає тестове середовище одразу після підписання тестової угоди. Детальніше про платіжну систему можна прочитати на Wikipedia.
Зв'яжіться з нами, щоб обговорити ваш проєкт. Оцініть ваш проєкт — підберемо оптимальний протокол і підготуємо ТЗ для банку. Інвестиції в інтеграцію окупаються за перший місяць роботи завдяки зниженню комісій та зростанню конверсії. Пишіть нам на [email protected] (замінити на реальний контакт).