Інтеграція 1С-Бітрікс з інтернет-еквайрингом Беларусбанк

Ми інтегруємо 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. Ось порівняльна таблиця:

Реальний кейс: білоруський інтернет-магазин спортивних товарів працював на старій SOAP-інтеграції. Після оновлення шлюзу банком SOAP почав повертати помилки Service Unavailable у години пік (до 50% відмов). Міграція на REST API зайняла 3 робочі дні — стабільність відновлено, відмови знизилися до 1%. Той випадок, коли оновлення протоколу окупилося за перший місяць. Загалом через нашу інтеграцію пройшло понад 100 000 транзакцій. Після переходу на REST конверсія оплат зросла на 15%.

Особливості платежів: Белкарт, 3D-Secure та обробка помилок

Белкарт і 3D-Secure

Еквайринг Беларусбанку включає процесинг карток Белкарт — національної платіжної системи Білорусі. Вони широко використовуються зарплатними клієнтами держпідприємств. При підключенні підтримка Белкарт вмикається автоматично, але ми обов'язково тестуємо оплату тестовою карткою Белкарт — не лише Visa/Mastercard.

Беларусбанк вимагає 3D-Secure для всіх карткових транзакцій. Покупець перенаправляється на сторінку підтвердження банку-емітента — у Бітрікс це прозоро. Логи потрібно аналізувати за errorCode з відповіді payment/status.

Типові помилки та їх вирішення

При коді 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 днів для балансу між конверсією та ризиком несплати.

Покрокове налаштування обробника

1. Отримайте тестові дані у Беларусбанку (merchantId, client_secret, notifyUrl).
2. Створіть кастомний обробник у /local/php_interface/include/sale_payment/belarusbank_acquiring/.
3. Реалізуйте методи: createPayment, getStatus, processNotify, refundPayment.
4. Налаштуйте notifyUrl в особистому кабінеті банку.
5. Проведіть тестові платежі в тестовому середовищі, включаючи сценарії помилок.

Що входить в роботу?

Наша інтеграція «під ключ» включає:

• кастомний обробник sale_payment з підтримкою REST API;
• налаштування повідомлень (notifyUrl, обробка нотифікацій);
• тестування в тестовому середовищі Беларусбанку;
• інтеграція з ЄРІП (якщо потрібно);
• документація та інструкція з експлуатації;
• передача доступів до тестового середовища;
• навчання вашого технічного спеціаліста (1 година);
• гарантія 6 місяців безкоштовних доопрацювань за рекламаціями;
• підтримка після запуску.

Обсяг робіт і терміни

Терміни: укладення договору з Беларусбанком — від 5 до 15 робочих днів. Розробка та тестування — 2–4 дні. Беларусбанк надає тестове середовище одразу після підписання тестової угоди. Детальніше про платіжну систему можна прочитати на Wikipedia.

Зв'яжіться з нами, щоб обговорити ваш проєкт. Оцініть ваш проєкт — підберемо оптимальний протокол і підготуємо ТЗ для банку. Інвестиції в інтеграцію окупаються за перший місяць роботи завдяки зниженню комісій та зростанню конверсії. Пишіть нам на [email protected] (замінити на реальний контакт).