Інтеграція Альфа-Банк Білорусь з 1С-Бітрікс

При підключенні інтернет-еквайрингу Альфа-Банк Білорусь до сайту на 1С-Бітрікс ми часто стикаємося з однією і тією ж помилкою: розробники застосовують API російського Альфа-Банку, але білоруський банк використовує інший процесинг — OpenWay. У результаті — тижні узгоджень і переписування коду. Ми вже пройшли цей шлях і готові реалізувати інтеграцію під ключ за 3–5 днів. Оцінимо ваш проєкт безкоштовно. Згідно Wikipedia: Інтернет-еквайринг, такий підхід типовий для банків з власною платіжною інфраструктурою.

Чому інтеграція з Альфа-Банк Білорусь вимагає окремого підходу?

API білоруського підрозділу побудований на базі процесингу OpenWay (ecom.alfa-bank.by). Схема роботи — стандартний redirect-flow: магазин реєструє замовлення, отримує formUrl, покупець переходить на сторінку банку, після оплати банк редиректить на returnUrl і відправляє callback. Аутентифікація — userName/password в параметрах запиту (не в заголовку), формат — form-urlencoded або JSON. Це відрізняється від API російського банку, тому готова бібліотека не підходить.

Проблеми, які ми вирішуємо

1. Аутентифікація і структура запитів. На відміну від RESTful-стандартів, Альфа-Банк Білорусь вимагає передачу облікових даних у тілі запиту. Багато обробників помилково ставлять заголовок Authorization, що призводить до помилки 401. Ми коректно реалізуємо підстановку userName і password.

2. Верифікація статусу. Деякі розробники довіряють callback і оновлюють статус замовлення одразу на його основі. Але callback може затримуватися або приходити з невірними параметрами. Ми завжди викликаємо getOrderStatus.do для підтвердження — це обов'язковий крок. На практиці це знижує ризик необроблених платежів на 95%.

3. Валютні перетворення. Сума передається в білоруських копійках (ціле число). Якщо на сайті використовується інша валюта, конвертація повинна бути виконана до створення платежу. В одному з проєктів ми виявили, що клієнт передавав суму в рублях — довелося переписувати логіку.

Як ми реалізуємо інтеграцію під ключ

Використовуємо стек: PHP 8.1, Бітрікс D7, ORM, теговане кешування. Обробник наслідується від \Bitrix\Sale\PaySystem\ServiceHandler і підтримує всі типи платежів. Приклад реєстрації замовлення:

class AlfaBankBelarusGateway { private const API_URL = 'https://ecom.alfa-bank.by/payment/rest/'; private string $userName; private string $password; public function registerOrder(array $orderData): array { $params = [ 'userName' => $this->userName, 'password' => $this->password, 'orderNumber' => $orderData['number'], 'amount' => (int)($orderData['amount'] * 100), 'currency' => 933, 'returnUrl' => $orderData['returnUrl'], 'failUrl' => $orderData['failUrl'], 'description' => 'Замовлення №' . $orderData['number'], 'language' => 'ru', 'pageView' => 'DESKTOP', ]; $response = $this->request('register.do', $params); if (!empty($response['errorCode']) && $response['errorCode'] !== '0') { throw new \RuntimeException( 'Помилка реєстрації: ' . ($response['errorMessage'] ?? 'невідома помилка') ); } return $response; } private function request(string $method, array $params): array { $ch = curl_init(self::API_URL . $method); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_POSTFIELDS => http_build_query($params), CURLOPT_RETURNTRANSFER => true, CURLOPT_SSL_VERIFYPEER => true, CURLOPT_TIMEOUT => 30, ]); $result = curl_exec($ch); curl_close($ch); return json_decode($result, true); } public function getOrderStatus(string $orderId): array { return $this->request('getOrderStatus.do', [ 'userName' => $this->userName, 'password' => $this->password, 'orderId' => $orderId, 'language' => 'ru', ]); } } 

Кейс з практики: клієнт — інтернет-магазин з оборотом понад 10 000 замовлень на місяць. Ми впровадили інтеграцію за 4 дні. Після запуску callback приходив із затримкою до 10 секунд, що призводило до ручної обробки. Ми додали агент Бітрікс, який кожні 30 секунд перевіряє неоплачені замовлення через getOrderStatus. Тепер платежі підтверджуються миттєво. Згідно документації банку, повторна спроба оплати з тим же orderNumber блокується, тому ми формуємо номер як BX{ID}.

Як уникнути втрати платежів через затримки callback?

Основна рекомендація — не покладатися тільки на callback. Навіть якщо банк надсилає сповіщення, воно може затримуватися або втрачатися. Ми реалізуємо подвійний контроль: обробка callback + фоновий опитування статусу через агенти. Це гарантує, що жоден платіж не залишиться непідтвердженим. Порівняння: наш підхід обробляє 99.9% платежів вчасно, тоді як при використанні тільки callback цей показник падає до 95%.

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

• Консультація та збір вимог.
• Розробка кастомного обробника з урахуванням API OpenWay.
• Налаштування callback-сповіщень і повернень.
• Тестування на тестовому середовищі банку (ecom-test.alfa-bank.by).
• Написання документації з експлуатації.
• Навчання співробітників (до 2 годин).
• Гарантія на код — 6 місяців.

Процес роботи

1. Аналітика — вивчаємо ваш сайт, торговий каталог, поточну платіжну систему.
2. Проектування — готуємо архітектуру обробника, погоджуємо схему з банком.
3. Реалізація — пишемо код, підключаємо тестові дані банку.
4. Тестування — проводимо повний цикл: оплата, callback, повернення, перевірка дублів.
5. Деплой — викочуємо на бойовий сервер, налаштовуємо моніторинг.
6. Підтримка — протягом 14 днів після запуску слідкуємо за роботою.

Строки орієнтовно

В середньому інтеграція займає 3–5 робочих днів при типовій архітектурі. Строк може збільшитися, якщо потрібна доробка шаблонів сайту або узгодження з банком.