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

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

Белагропромбанк — один из ключевых государственных банков Беларуси, с сильной позицией в агропромышленном секторе и регионах страны. Интернет-эквайринг банка поддерживает карты Visa, Mastercard и Белкарт. Для сельскохозяйственных предприятий, интернет-магазинов агротоваров и региональных ритейлеров, чей основной банк — Белагропромбанк, подключение его эквайринга — логичный выбор: платёжный шлюз и расчётный счёт в одном банке упрощают сверку.

API Белагропромбанка

Банк предоставляет REST API для интернет-эквайринга. Эндпоинт: https://payment.bapb.by/api/v2/ (продакшн), тестовый — предоставляется по запросу после заключения тестового соглашения.

Аутентификация: Basic Auth (merchantLogin:merchantPassword) или токен через OAuth 2.0 (зависит от версии договора).

Ключевые операции:

• POST /orders — регистрация нового заказа в системе шлюза
• GET /orders/{orderId}/status — проверка статуса транзакции
• POST /orders/{orderId}/void — отмена авторизации
• POST /orders/{orderId}/refund — возврат средств
• POST /erip/bills — создание счёта в ЕРИП

Реализация обработчика в Битрикс

Стандартная схема — кастомный обработчик платёжной системы в /local/php_interface/include/sale_payment/bapb_acquiring/.

Запрос регистрации заказа:

{
  "merchantId": "BAPB_MERCHANT_ID",
  "orderNumber": "BXORDER_34567",
  "amount": 156800,
  "currency": "BYN",
  "returnUrl": "https://shop.by/order/success/34567/",
  "failUrl": "https://shop.by/order/fail/34567/",
  "notificationUrl": "https://shop.by/bitrix/tools/sale_ps_result.php",
  "description": "Интернет-магазин: заказ №34567",
  "sessionTimeoutSecs": 1200
}

sessionTimeoutSecs — время жизни платёжной сессии в секундах. По умолчанию 1200 (20 минут). Если покупатель не завершает оплату за это время, сессия закрывается. В Битрикс важно это учитывать при отображении страницы «ожидание оплаты».

Белкарт: специфика

Белагропромбанк — один из эмитентов карт Белкарт в Беларуси, поэтому его эквайринг особенно надёжен для приёма карт Белкарт. Технически отличий в запросе нет — шлюз автоматически определяет тип карты. Но при тестировании обязательно проверять оплату именно картой Белкарт: иногда банки имеют разные лимиты для Белкарт vs Visa/Mastercard.

Нотификации и статусы

POST-нотификации на notificationUrl:

Верификация нотификации — HMAC-SHA256 или через IP-whitelist (список IP Белагропромбанка). Уточнять у банка при подключении.

Двухстадийная оплата

Для товаров под заказ или с проверкой наличия банк поддерживает двухстадийную схему:

1. POST /orders с параметром twoStage: true — только блокировка суммы (статус APPROVED)
2. POST /orders/{orderId}/deposit — фактическое списание после подтверждения наличия

В Битрикс это реализуется через кнопку «Подтвердить списание» в административной части заказа — метод ProcessRequestDeposit обращается к API банка.

Отчётность и сверка

Белагропромбанк предоставляет API для получения реестров транзакций: GET /reports/transactions?dateFrom=...&dateTo=.... Для бухгалтерии это удобно — автоматически скачивать отчёт в конце дня и сверять с данными в Битрикс. Если расхождения — сигнал о необработанных нотификациях.

Реальный кейс: задержка возврата средств

Белорусский магазин садовой техники. Покупатель вернул товар, менеджер нажал «Сделать возврат» в административной части Битрикс — API вернул success. Но деньги на карте покупателя появились через 8 рабочих дней вместо ожидаемых 3. Причина: магазин работал по договору с двухстадийной оплатой, и для возврата по «зарезервированной» (не списанной) сумме нужно было использовать метод void, а не refund. Метод refund применялся к уже списанным суммам и проходил через более длинный процессинговый цикл. Исправили условие в обработчике — void при статусе APPROVED, refund при DEPOSITED.

Сроки