Seamless Hutkі Grosh Payment Integration for 1C-Bitrix

The problem: offline buyers can't pay online

In Belarus, a significant portion of buyers don't use bank cards – they actively pay through Hutkі Grosh self-service terminals. If your 1C-Bitrix store doesn't accept these payments, you're losing up to 30% of your audience from the regions. We solve this by integrating Hutkі Grosh with your 1C-Bitrix store, allowing customers to pay at any terminal, gas station, or post office. Our experience shows that after integration, conversion to payment for such orders reaches 85–90%.

How the Hutkі Grosh integration with Bitrix works

Once connected, you gain an additional payment channel with no card acquiring fees. The customer selects “Pay via terminal” at checkout, receives a payment code, and visits a nearby terminal. Within minutes, the order is automatically confirmed – no manager intervention needed. We have over 5 years of Bitrix experience and have successfully integrated more than 50 payment systems, confirming our expertise.

Technical mechanism: from XML request to confirmation

Hutkі Grosh provides an XML-based API, based on the CommerceML protocol (adapted for payment requests). The workflow:

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

Unlike card acquiring, payment may arrive hours or days later – the customer chooses the convenient moment. This is especially important in regions where Hutkі Grosh terminals are installed at every Belpochta branch.

How to develop a custom handler?

There is no official module, so we implement a custom one 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>2027-12-25</expire_date> <signature>md5_hash</signature> </request> 

The amount is in Belarusian kopecks. The signature is MD5 of merchant_id + order_id + amount + currency + secret_key. The expire_date is generated dynamically (typically +7 days).

Display to the customer and AJAX polling

After creating the invoice, you need to show:

• Payment code (10–12 digits) – to be entered at the terminal
• Instructions: "Select Hutkі Grosh → Pay by code → Enter code"
• A terminal map (provided by Hutkі Grosh)
• Code validity period (usually 3–7 days)
• QR code for mobile app payment

In the component template, it's crucial to implement a waiting page with AJAX polling of the status – customers often return to the site after payment and want to see confirmation.

Handling callback notifications

Hutkі Grosh sends an XML notification to the callback_url:

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

The order of processing in processRequest:

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

If you don't return a correct response, the system will retry for up to 24 hours.

Expiration and cancellation

When the expire_date passes, the system changes the status to EXPIRED. We recommend setting up a cron job to check:

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

What the work includes

• Development of a custom handler (payment system, template, callback handler)
• Setup of a waiting page with AJAX polling
• Integration with your shopping cart and checkout component
• Testing on the production environment
• Documentation for the handler and operator instructions
• 6-month code warranty

We have over 5 years of Bitrix experience and have successfully integrated more than 50 payment systems. This expertise is backed by 1C-Bitrix certificates.

Case study: automating weekend payments

From our client's practice: a Belarusian building materials store. Customers paid via terminals on Friday evenings and Saturdays; callbacks arrived on time, but managers didn't work on weekends and there was no automatic processing. Orders remained pending until Monday. We set up automatic order confirmation via callback without manager involvement and added Telegram notifications. As a result, 40% of orders started being confirmed instantly, and repeat purchase conversion increased by 15%.

Comparison of Hutkі Grosh with card acquiring

The comparison shows that Hutkі Grosh confirms payments 2x faster in regions where cards are rarely used, and the commission is 30% lower.

Why might the callback not arrive?

First, check the callback_url accessibility from the external network. Also ensure the handler returns <result>OK</result> – otherwise, Hutkі Grosh will keep retrying for up to 24 hours. We include callback monitoring in our warranty service.

Estimated timelines

Cost is determined individually after analysis of your store. Order a turnkey integration – we will assess your project for free and offer the optimal solution. Get a consultation on integration – just contact us.