Integration of 1C-Bitrix with the Halyk Bank payment system (Kazakhstan)

1C-Bitrix Integration with Halyk Bank Payment System (Kazakhstan)

Halyk Bank is the largest bank in Kazakhstan. It provides internet acquiring for online stores through the Halyk eCommerce payment gateway (formerly HomeBank). Accepts Visa, Mastercard, American Express cards, as well as payments through the Halyk mobile application.

Integration Architecture

Halyk Bank provides several connection options:

Halyk eCommerce (Redirected Payment) — redirect to the bank's payment form. Most common, does not require PCI DSS certification.

Halyk API (Direct Payment) — the store accepts card data directly. Requires PCI DSS.

HalykPay — payment through the Halyk mobile application (similar to Kaspi Pay).

Standard Bitrix integration is via Redirected Payment.

Parameters and Payment Creation

Halyk uses its own SSL signature protocol. The store receives from the bank:

• terminal — terminal identifier
• client_id — login
• client_secret — password
• Gateway URL — test and production

Getting 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 №' . $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 when payment or error occurs:

$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: CHARGED — successfully debited, DECLINED — rejected by bank, CANCELLED — cancelled, AUTHENTICATED — authorized (awaiting confirmation in two-stage scheme).

Two-Stage Payments

Halyk supports the "authorization + confirmation" scheme:

// Create invoice with parameter "preAuth": true
$invoiceData['preAuth'] = true;

// After order processing — confirm debit
$confirmData = [
    'invoice_id' => $halykInvoiceId,
    'amount'     => $amount,
];
$this->httpPost('https://epayment.halykbank.kz/api/public/v1/confirm', $confirmData, $headers);

// Or cancel hold
$this->httpPost('https://epayment.halykbank.kz/api/public/v1/cancel', ['invoice_id' => $halykInvoiceId], $headers);

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']
);

Characteristics

• Access token has a limited lifespan. Implement caching and refresh: on 401 error, request token again and retry the request
• invoiceId — your order identifier, id in the response — Halyk's internal ID. Both need to be saved for refunds and verification
• Test environment: https://test.epayment.halykbank.kz. Test cards are provided by the bank during registration

Development Timeline