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

Інтеграція 1С-Bitrix з платіжною системою 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).

Стандартна інтеграція з Bitrix — через 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. Тестові карти надає банк при реєстрації

Терміни розробки