Integration of 1C-Bitrix with the Hutki Grosh payment system (Belarus)

1C-Bitrix Integration with the Hutkі Grosh Payment System (Belarus)

"Hutkі Grosh" ("Fast Money") is a Belarusian instant payment system focused on payments via self-service terminals and internet banking. The system's core audience consists of customers from Belarusian regions where Hutkі Grosh terminals are available in grocery stores, petrol stations, and post offices. Integrating with 1C-Bitrix addresses the challenge of reaching this audience — people who do not use bank cards for online payments but actively pay through terminals.

Technical Mechanism

Hutkі Grosh provides an XML-based API for invoicing. The workflow:

1. The store registers an invoice via API (POST XML packet to the Hutkі Grosh gateway)
2. The system returns a transactionId and paymentCode
3. The customer pays using the code at a terminal, through the Hutkі Grosh internet wallet, or via the mobile app
4. The system sends a notification to the store's callbackUrl

Unlike card acquiring, payment may arrive several hours or even days after the invoice is created — the customer finds a convenient terminal and pays offline.

Developing the Handler in 1C-Bitrix

There is no official Hutkі Grosh module for 1C-Bitrix. The implementation is a custom handler at /local/php_interface/include/sale_payment/hutki_grosh/.

The API accepts 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>Payment for order #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>

The amount in the request is in Belarusian kopecks. signature — MD5 of merchant_id + order_id + amount + currency + secret_key.

The response contains transaction_id and payment_code to display to the customer.

Customer-Facing Display

After the invoice is created, the customer must be shown:

• Payment code (typically 10–12 digits) — entered at the terminal
• Instructions: "Select Hutkі Grosh → Pay by code → Enter code"
• Terminal locations (Hutkі Grosh provides a map)
• Code expiry period (usually 3–7 days)
• QR code for payment via the Hutkі Grosh mobile app

In the payment system component template (template/), it is important to implement a waiting page with AJAX status polling — customers often return to the site after paying at a terminal and expect to see a confirmed order.

Handling Callback Notifications

Hutkі Grosh sends an XML notification to 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>

Processing order in processRequest:

1. Parse XML (SimpleXMLElement or DOMDocument)
2. Verify signature
3. Check amount match
4. Find the payment by order_id in the b_sale_payment table
5. On PAID status, call $payment->setPaid('Y')
6. Return XML response <response><result>OK</result></response>

If a proper response is not returned, the system will retry for up to 24 hours.

Expiry and Cancellation

When expire_date is reached, the system changes the invoice status to EXPIRED and may send a corresponding callback. It is recommended to set up a cron job to check invoices nearing expiry:

// Request current status
$response = $this->apiRequest('GET', '/invoice/' . $transactionId);
if ($response['status'] === 'EXPIRED') {
    // Update order status, notify customer
}

Real Case: Unprocessed Payments on Weekends

A Belarusian building materials store. Customers paid via terminals on Friday evenings and Saturday; callbacks arrived on time — but managers did not work on weekends, and no automatic notification processing had been configured. Orders sat in "Awaiting payment" status until Monday. Fix: configure automatic order confirmation and status change to "Paid" on callback without manager involvement, and add a Telegram channel notification for newly paid orders.

Timeline

Connecting to Hutkі Grosh involves: registering as a service provider, signing a contract, and technical onboarding. This takes 2 to 4 weeks in total. Handler development and testing in 1C-Bitrix takes 3–5 business days and can run in parallel with the paperwork.