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

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

Assist Belarus — білоруський процесинговий платіжний шлюз, що агрегує кілька способів оплати: картки Visa/Mastercard/Белкарт, ЄРІР та інші. Для білоруських інтернет-магазинів це зручний варіант: одне підключення закриває картковий еквайринг та ЄРІР без необхідності працювати з кожним банком окремо. Технічно інтеграція будується через REST API Assist, який за архітектурою нагадує російські шлюзи, але має свою специфіку.

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

Assist виступає агрегатором: магазин підключається до одного шлюзу, а кінцевий процесинг (Белкарт, Visa, ЄРІР) відбувається на стороні 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 Belarus підтримує операції в BYN, USD, EUR. Якщо в магазині ціни в BYN, а покупець хоче платити карткою в USD, Assist виконує конвертацію за курсом Нацбанку на момент транзакції. У Бітрікс важливо правильно передавати код валюти — ISO 4217 (BYN, USD, EUR), а не символьні позначення (р., $).

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

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

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

Реальний кейс: подвійне списання

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

Терміни

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