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

Интеграция 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:

Обработка нотификаций

Беларусбанк отправляет 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 рабочих дня. Беларусбанк предоставляет тестовую среду с тестовыми картами сразу после подписания тестового соглашения.