Интеграция 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 рабочих дней параллельно с оформлением документов.