Інтеграція 1С-Бітрікс з платіжною системою Hutkі Грош (Білорусь)

Інтеграція 1С-Бітрікс з платіжною системою Hutkі Грош (Білорусь)

«Hutkі Грош» («Швидкі гроші») — білоруська система миттєвих платежів, орієнтована на оплату через термінали самообслуговування та інтернет-банкінг. Особлива аудиторія цієї системи — покупці з регіонів Білорусі, де термінали Hutkі Грош присутні в продуктових магазинах, на заправках та у відділеннях пошти. Інтеграція з Бітрікс вирішує завдання охоплення цієї аудиторії, яка не використовує банківські картки для онлайн-оплати, але активно платить через термінали.

Технічний механізм роботи

Hutkі Грош надає XML-based API для виставлення рахунків. Схема роботи:

1. Магазин реєструє рахунок через API (POST XML-пакету на шлюз Hutkі Грош)
2. Система повертає transactionId та paymentCode
3. Покупець оплачує за кодом у терміналі, через інтернет-гаманець Hutkі Грош або через застосунок
4. Система надсилає нотифікацію на callbackUrl магазину

На відміну від карткового еквайрингу, оплата може надійти через кілька годин або днів після створення рахунку — покупець знаходить зручний термінал і оплачує офлайн.

Розробка обробника в Бітрікс

Офіційного модуля Hutkі Грош для Бітрікс не існує. Реалізація — кастомний обробник у /local/php_interface/include/sale_payment/hutki_grosh/.

API приймає XML:

<?xml version="1.0" encoding="UTF-8"?>
<request>
  <service_id>YOUR_SERVICE_ID</service_id>
  <merchant_id>YOUR_MERCHANT_ID</merchant_id>
  <order_id>BXORDER_78901</order_id>
  <amount>125000</amount>
  <currency>BYN</currency>
  <description>Оплата замовлення №78901</description>
  <callback_url>https://shop.by/bitrix/tools/sale_ps_result.php</callback_url>
  <return_url>https://shop.by/personal/order/detail/78901/</return_url>
  <expire_date>2024-12-25</expire_date>
  <signature>md5_hash</signature>
</request>

Сума в запиті — в білоруських копійках. signature — MD5 від merchant_id + order_id + amount + currency + secret_key.

Відповідь містить transaction_id та payment_code для відображення покупцю.

Відображення покупцю

Після створення рахунку покупцю потрібно показати:

• Код платежу (зазвичай 10–12 цифр) — вводиться в терміналі
• Інструкцію: «Обрати Hutkі Грош → Оплата за кодом → Ввести код»
• Точки присутності терміналів (Hutkі Грош надає карту)
• Термін дії коду (як правило, 3–7 днів)
• QR-код для оплати через застосунок Hutkі Грош

У шаблоні компонента платіжної системи (template/) важливо реалізувати сторінку очікування з AJAX-поллінгом статусу замовлення — покупці часто повертаються на сайт після оплати через термінал і очікують побачити підтверджене замовлення.

Обробка callback-сповіщень

Hutkі Грош надсилає XML-сповіщення на callback_url:

<notification>
  <transaction_id>hg_txn_556677</transaction_id>
  <order_id>BXORDER_78901</order_id>
  <status>PAID</status>
  <amount>125000</amount>
  <paid_at>2024-12-23T09:15:00+03:00</paid_at>
  <signature>md5_verification_hash</signature>
</notification>

Порядок обробки в processRequest:

1. Розпарсити XML (SimpleXMLElement або DOMDocument)
2. Верифікувати signature
3. Перевірити відповідність суми
4. Знайти платіж за order_id у таблиці b_sale_payment
5. При статусі PAID викликати $payment->setPaid('Y')
6. Повернути XML-відповідь <response><result>OK</result></response>

Якщо не повернути коректну відповідь, система повторюватиме спроби до 24 годин.

Закінчення терміну та скасування

Після закінчення expire_date система змінює статус рахунку на EXPIRED і може надіслати відповідний callback. Рекомендується налаштувати cron-задачу для перевірки рахунків із терміном, що спливає:

// Запит актуального статусу
$response = $this->apiRequest('GET', '/invoice/' . $transactionId);
if ($response['status'] === 'EXPIRED') {
    // Оновити статус замовлення, повідомити покупця
}

Реальний кейс: необроблені оплати у вихідні

Білоруський магазин будівельних матеріалів. Покупці платили через термінали в п'ятницю ввечері та в суботу, callback надходив вчасно — але менеджери не працювали у вихідні, а автоматичної обробки нотифікацій налаштовано не було. Замовлення зависали в статусі «Очікування оплати» до понеділка. Рішення: налаштувати автоматичне підтвердження замовлення та зміну статусу на «Оплачено» за callback без участі менеджера, додати сповіщення на Telegram-канал про нові оплачені замовлення.

Терміни

Підключення до Hutkі Грош включає: реєстрацію як постачальника послуг, підписання договору та технічний onboarding. Все це займає від 2 до 4 тижнів. Розробка та тестування обробника в Бітрікс — 3–5 робочих днів паралельно з оформленням документів.