Інтеграція 1С-Бітрікс з платіжною системою Assist Belarus

Інтеграція 1С-Бітрікс з платіжною системою Assist Belarus

Ми часто стикаємося з ситуацією, коли білоруський інтернет-магазин намагається підключити Assist Belarus, але стикається з подвійними списаннями або невірною верифікацією підписів. Наш досвід показує: правильно налаштований обробник позбавляє від 80% проблем на старті. За роки роботи ми накопичили експертизу, що дозволяє уникнути таких помилок: невірного підпису, неврахованих статусів і втрати нотифікацій. Assist Belarus — платіжний шлюз (Wikipedia) білоруського процесингу, що агрегує карти (Visa/Mastercard/Белкарт) та ЄРІП. Для магазину це одне підключення замість кількох банківських договорів. Технічно інтеграція будується через REST API Assist; ми реалізували її для 15+ проєктів, гарантуючи коректну обробку всіх статусів і захист від повторних списань.

Принцип роботи Assist Belarus

Assist виступає агрегатором: магазин підключається до одного шлюзу, а кінцевий процесинг відбувається на стороні Assist. Схема взаємодії:

1. Магазин формує запит до API Assist (https://payments.assist.by/) з параметрами замовлення
2. Assist повертає orderId та URL платіжної сторінки
3. Покупець обирає спосіб оплати та платить на сторінці Assist
4. Assist надсилає POST-нотифікацію на callback_url магазину
5. Магазин верифікує дані та підтверджує замовлення

API працює через HTTPS POST з параметрами в тілі запиту (application/x-www-form-urlencoded) або в JSON залежно від версії API.

Налаштування обробника в Бітрікс

Assist Belarus не має офіційного модуля в Маркетплейс Бітрікс, тому інтеграція реалізується через кастомний обробник платіжної системи модуля sale.

Розміщення: /local/php_interface/include/sale_payment/assist_belarus/ Ключові налаштування (.settings.php):

return [ 'MERCHANT_ID' => ['NAME' => 'Merchant ID', 'SORT' => 100], 'LOGIN' => ['NAME' => 'Логін в Assist', 'SORT' => 200], 'PASSWORD' => ['NAME' => 'Пароль', 'SORT' => 300], 'TEST_MODE' => ['NAME' => 'Тестовий режим', 'SORT' => 400], 'CURRENCY' => ['NAME' => 'Валюта (BYN/USD)', 'SORT' => 500], ]; 

Метод initiatePay формує запит на створення рахунку:

$params = [ 'Merchant_ID' => $this->getParam('MERCHANT_ID'), 'OrderNumber' => $order->getField('ACCOUNT_NUMBER'), 'OrderAmount' => number_format($payment->getSum(), 2, '.', ''), 'OrderCurrency'=> $this->getParam('CURRENCY'), 'URL_RETURN' => $returnUrl, 'URL_RETURN_NO'=> $failUrl, 'callbackType' => 'server', 'callbackURL' => $callbackUrl, 'Language' => 'RU', ]; 

Верифікація нотифікацій

Assist передає підпис через параметр Signature — MD5 або SHA256 від конкатенації Merchant_ID, OrderNumber, OrderAmount, OrderCurrency та секретного ключа. Порядок полів фіксований і вказаний в документації.

Обробка нотифікації в processRequest:

$expectedSign = md5( $merchantId . $orderNumber . $orderAmount . $currency . $secretKey ); if ($expectedSign !== strtolower($_POST['Signature'])) { throw new \Exception('Invalid signature'); } $status = $_POST['OrderState']; if ($status === 'Approved') { $payment->setPaid('Y'); $payment->save(); } 

Статуси Assist: Approved (оплачено), Declined (відхилено), Cancelled (скасовано), Pending (очікує).

Як уникнути подвійного списання при інтеграції з Assist?

З практики: один наш клієнт — магазин білоруської косметики — зіткнувся з тим, що у кількох покупців гроші списалися двічі. Аналіз логів показав: покупець натискав «Оплатити», сторінка зависала (повільний хостинг), він натискав ще раз — формувалося два запити до Assist з різними OrderNumber (Бітрікс створив два платежі для одного замовлення). Рішення: додати кнопку disabled після першого кліку на JS-рівні та перевірку на стороні Бітрікс — не створювати новий платіж, якщо у замовлення вже є активний необроблений.

За даними документації Assist, повторні запити з однаковим OrderNumber також блокуються шлюзом, але краще покладатися на власний захист.

Валютні операції

Assist Belarus підтримує операції в BYN, USD, EUR. Якщо в магазині ціни в BYN, а покупець хоче платити карткою в USD, Assist виконує конвертацію за курсом Нацбанку на момент транзакції. У Бітрікс важливо правильно передавати код валюти — ISO 4217 (BYN, USD, EUR), а не символьні позначення (р., $).

Робота з ЄРІП через Assist

При підключенні ЄРІП через агрегатор Assist покупцю на сторінці оплати пропонується вибір: «Карта» або «ЄРІП». При виборі ЄРІП Assist повертає реквізити для оплати — номер в ЄРІП та QR-код. Магазин отримує нотифікацію так само, як при картковій оплаті.

Перевага агрегаторної схеми — не потрібно окремо реєструватися в дереві ЄРІП: Assist робить це за вас в рамках договору. Але код послуги в дереві буде прив'язаний до Assist, а не безпосередньо до вашої компанії.

Порівняння: Assist Belarus vs пряма інтеграція з банком

Assist Belarus виграє за швидкістю підключення — в середньому в 3 рази швидше, ніж пряма інтеграція з банком. Однак для великих оборотів пряма інтеграція може бути вигіднішою за комісією.

Статуси нотифікацій Assist

Що входить в роботу з інтеграції

• Розробка кастомного обробника під модуль sale
• Налаштування callback-повідомлень та верифікації підписів
• Тестування всіх сценаріїв: успішна оплата, скасування, помилка
• Підготовка документації з експлуатації
• Навчання співробітників роботі з платіжним шлюзом
• Підтримка після запуску протягом місяця

Строки

Assist Belarus надає тестовий доступ протягом 1–3 днів після подачі заявки. Розробка обробника та тестування — 2–4 робочі дні. Повна активація бойового акаунту після перевірки сайту — 3–7 робочих днів.

Чому варто обрати агрегаторну схему ЄРІП через Assist?

Тому що вона скорочує час виходу на ринок: не потрібно чекати реєстрації в дереві ЄРІП (зазвичай 2–4 тижні). Assist робить це швидше. Але враховуйте, що тарифи агрегатора можуть бути вищими, ніж при прямому підключенні. Ми допоможемо прорахувати обидва варіанти та вибрати оптимальний.

Ми працюємо з платіжними інтеграціями понад 8 років, за цей час реалізували більше 50 проєктів для Бітрікс. Звертайтеся: допоможемо оцінити проєкт та запропонуємо рішення під ключ. Щоб отримати консультацію з інтеграції, напишіть нам — оцінимо ваш проєкт за 1 день.