Интеграция 1С-Битрикс с платежной системой Halyk Bank (Казахстан)

Интеграция 1С-Битрикс с платёжной системой Halyk Bank (Казахстан)

Halyk Bank — крупнейший банк Казахстана. Предоставляет интернет-эквайринг для онлайн-магазинов через платёжный шлюз Halyk eCommerce (ранее HomeBank). Принимает карты Visa, Mastercard, карты American Express, а также оплату через мобильное приложение Halyk.

Архитектура интеграции

Halyk Bank предоставляет несколько вариантов подключения:

Halyk eCommerce (Redirected Payment) — редирект на платёжную форму банка. Наиболее распространён, не требует сертификации PCI DSS.

Halyk API (Direct Payment) — магазин принимает данные карты напрямую. Требует PCI DSS.

HalykPay — оплата через мобильное приложение Halyk (аналог Kaspi Pay).

Стандартная интеграция с Битрикс — через Redirected Payment.

Параметры и создание платежа

Halyk использует собственный SSL-протокол подписи. Магазин получает от банка:

• terminal — идентификатор терминала
• client_id — логин
• client_secret — пароль
• URL шлюза — тестовый и боевой

Получение токена доступа:

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

Создание платежа:

$orderId = $payment->getOrder()->getId();
$amount  = $payment->getSum();  // в тенге

$invoiceData = [
    'amount'      => $amount,
    'currency'    => 'KZT',
    'terminal'    => $terminal,
    'invoiceId'   => $orderId,
    'description' => 'Заказ №' . $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;
// Редирект покупателя на $paymentUrl

Обработка callback уведомлений

Halyk отправляет POST на postLink при оплате или ошибке:

$rawBody = file_get_contents('php://input');
$data    = json_decode($rawBody, true);

$invoiceId  = $data['id'];         // ID счёта Halyk
$orderId    = $data['invoiceId'];  // наш orderId
$txStatus   = $data['status'];     // 'CHARGED', 'DECLINED', 'CANCELLED'

// Верификация: запросить статус через 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);

Статусы: CHARGED — успешно списано, DECLINED — отклонено банком, CANCELLED — отменено, AUTHENTICATED — авторизован (ждёт подтверждения при двухстадийной схеме).

Двухстадийные платежи

Halyk поддерживает схему «авторизация + подтверждение»:

// Создать инвойс с параметром "preAuth": true
$invoiceData['preAuth'] = true;

// После обработки заказа — подтвердить списание
$confirmData = [
    'invoice_id' => $halykInvoiceId,
    'amount'     => $amount,
];
$this->httpPost('https://epayment.halykbank.kz/api/public/v1/confirm', $confirmData, $headers);

// Или отмена холда
$this->httpPost('https://epayment.halykbank.kz/api/public/v1/cancel', ['invoice_id' => $halykInvoiceId], $headers);

Возвраты

$refundData = [
    'invoice_id' => $halykInvoiceId,
    'amount'     => $refundAmount,
    'reason'     => 'Возврат по заказу',
];

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

Особенности

• Токен доступа имеет ограниченный срок жизни. Реализуйте его кеширование и обновление: при ошибке 401 повторно запрашивайте токен и повторяйте запрос
• invoiceId — ваш идентификатор заказа, id в ответе — внутренний ID Halyk. Оба нужно сохранять для возвратов и проверки
• Тестовая среда: https://test.epayment.halykbank.kz. Тестовые карты предоставляет банк при регистрации

Сроки разработки