Інтеграція 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.

Терміни