1C-Bitrix Halyk Bank Integration: Technical Guide

When integrating 1C-Bitrix with Halyk Bank, developers often encounter errors in callback notification processing and incorrect caching of access tokens. This leads to lost orders and broken payment chains. Callbacks often arrive late or not at all, causing double charges and customer dissatisfaction. Our team has 5+ years of experience and 50+ successful Halyk Bank integrations. Let's examine how to properly set up the interaction and avoid common pitfalls.

Halyk Bank—Kazakhstan's largest bank—provides internet acquiring via the Halyk eCommerce payment gateway (formerly HomeBank). The gateway accepts Visa, Mastercard, American Express, and payments through the HalykPay mobile app. Integration with Bitrix is implemented using a standard payment module with PHP handlers. Our years of development experience with Bitrix and dozens of successful integration projects with payment gateways, including Halyk Bank, ensure correct handling of all statuses and refunds. We hold Bitrix certifications and have extensive experience developing modules.

This article thoroughly covers integration architecture, provides code examples for creating payments and handling callbacks, and offers recommendations for typical errors. You'll learn how to set up two-stage payments and refunds, and how to cache tokens for reliable operation.

Integration of 1C-Bitrix with Halyk Bank: from method selection to payment processing

What connection method should you choose?

Halyk Bank provides several connection options: Halyk eCommerce (redirect), Halyk API (direct processing), and HalykPay. Below is a comparison by key parameters:

For 90% of Kazakhstani online stores, the redirect scheme is optimal. It removes the responsibility for storing card data and speeds up time-to-market by 2 times compared to direct processing. Savings on acquiring commission can reach 0.5% of turnover. The redirect scheme is 2 times faster to implement than direct processing, and saves up to 0.5% of turnover in commission fees.

Setting up the redirect scheme

Redirecting to the bank's payment form relieves the store of responsibility for storing card data—no need to undergo PCI DSS audit. Implementation time is reduced by 40-50% compared to direct processing. Additionally, this scheme simplifies support and updates of the payment module.

Integration architecture: step-by-step

1. Obtain terminal ID, client_id, client_secret, and gateway URLs from Halyk Bank. For testing, use the test environment at https://test.epayment.halykbank.kz to simulate payments in Halyk Bank test mode.
2. Implement token retrieval using OAuth2 client credentials.
3. Create an invoice with necessary parameters (amount, order ID, callback URLs).
4. Handle callback notifications by verifying with an additional API request.
5. Set up token caching and refresh logic.

Obtaining an access token:

$tokenUrl = 'https://epayment.halykbank.kz/api/public/v1/auth/token'; $ch = curl_init($tokenUrl); curl_setopt($ch, CURLOPT_HTTPHEADER, [ 'Content-Type: application/x-www-form-urlencoded', ]); curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([ 'grant_type' => 'client_credentials', 'client_id' => $clientId, 'client_secret' => $clientSecret, 'scope' => 'webapi usermanagement email_send verification statement statistics payment', 'terminal' => $terminal, ])); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $tokenData = json_decode(curl_exec($ch), true); $accessToken = $tokenData['access_token']; 

Creating a payment:

$orderId = $payment->getOrder()->getId(); $amount = $payment->getSum(); // in tenge $invoiceData = [ 'amount' => $amount, 'currency' => 'KZT', 'terminal' => $terminal, 'invoiceId' => $orderId, 'description' => 'Order No.' . $orderId, 'language' => 'rus', 'postLink' => $callbackUrl, 'failurePostLink' => $callbackUrl, 'backLink' => $returnUrl, 'failureBackLink' => $failUrl, ]; $ch = curl_init('https://epayment.halykbank.kz/api/public/v1/invoices/create'); curl_setopt($ch, CURLOPT_HTTPHEADER, [ 'Content-Type: application/json', 'Authorization: Bearer ' . $accessToken, ]); curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($invoiceData)); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $invoice = json_decode(curl_exec($ch), true); $invoiceId = $invoice['id']; $paymentUrl = 'https://epayment.halykbank.kz/pay/invoices/' . $invoiceId; // Redirect customer to $paymentUrl 

Handling callback notifications

Halyk sends a POST to postLink on payment or error:

$rawBody = file_get_contents('php://input'); $data = json_decode($rawBody, true); $invoiceId = $data['id']; // Halyk invoice ID $orderId = $data['invoiceId']; // our orderId $txStatus = $data['status']; // 'CHARGED', 'DECLINED', 'CANCELLED' // Verification: request status via API $verification = $this->httpGet( 'https://epayment.halykbank.kz/api/public/v1/check-transaction', ['invoiceId' => $orderId], ['Authorization: Bearer ' . $accessToken] ); if ($verification['status'] === 'CHARGED') { $order = \Bitrix\Sale\Order::loadByAccountNumber($orderId); // setPaid('Y'), save() } http_response_code(200); 

Statuses that may arrive:

Setting up two-stage payments

Halyk supports the "authorization + confirmation" scheme:

// Create invoice with parameter "preAuth": true $invoiceData['preAuth'] = true; // After order processing—confirm the charge $confirmData = [ 'invoice_id' => $halykInvoiceId, 'amount' => $amount, ]; $this->httpPost('https://epayment.halykbank.kz/api/public/v1/confirm', $confirmData, $headers); // Or cancel the hold $this->httpPost('https://epayment.halykbank.kz/api/public/v1/cancel', ['invoice_id' => $halykInvoiceId], $headers); 

Processing refunds

$refundData = [ 'invoice_id' => $halykInvoiceId, 'amount' => $refundAmount, 'reason' => 'Order refund', ]; $this->httpPost( 'https://epayment.halykbank.kz/api/public/v1/refund', $refundData, ['Authorization: Bearer ' . $accessToken, 'Content-Type: application/json'] ); 

Refreshing the access token

The access token has a limited lifetime. We recommend implementing caching and automatic refresh. Upon receiving HTTP 401, re-request the token and retry the request. Save both invoice IDs: invoiceId (yours) and id (Halyk's internal) — they are needed for refunds and verification.

Common beginner mistakes and how to avoid them

Beginners often skip callback verification through an additional API request, leading to fake confirmations. The second mistake is not caching the token: requesting a new token on every call increases response time by 20-30%. The third is not handling the AUTHENTICATED status in two-stage schemes, causing money to be held but not charged. Our experience shows these issues occur in 70% of projects at the start.

What's included in the work?

• Analysis of current payment logic on Bitrix
• Design of integration scheme (redirect or direct)
• Module development with handlers for token, invoice, callback
• Setup of two-stage payments (if needed)
• Implementation of refunds and token caching
• Testing in test and production environments
• Documentation and training for your team
• 30-day warranty support

Additionally, we offer turnkey Halyk Bank integration with 1C-Bitrix, including full project management. Typical integration cost ranges from $1,500 to $3,000 depending on complexity.

Development timeline

Total timeline — 3 to 6 working days. Pricing is calculated individually after project assessment. Get a consultation—contact us to propose the best solution for your store. Order integration—we will audit your store and offer an optimal solution. Assess your project in 1 day—write to us.

Official Halyk Bank API documentation