При інтеграції 1С-Бітрікс з Halyk Bank розробники часто стикаються з помилками в обробці callback-повідомлень та некоректним кешуванням токенів доступу. Це призводить до втрати замовлень і розриву ланцюжка оплати. Часто callback приходить із затримкою або не приходить взагалі, що викликає подвійні списання та невдоволення покупців. Розберімося, як правильно налаштувати взаємодію та уникнути типових проблем, заощадивши до 500 000 тенге на рік завдяки автоматизації.
Halyk Bank — найбільший банк Казахстану, надає інтернет-еквайринг через платіжний шлюз Halyk eCommerce (раніше HomeBank). Шлюз приймає карти Visa, Mastercard, American Express, а також оплату через мобільний додаток HalykPay. Інтеграція з Бітрікс реалізується через стандартний платіжний модуль з обробниками на PHP. Наш багаторічний досвід розробки на Бітрікс (5+ років) та понад 50 успішних кейсів інтеграції з платіжними шлюзами, включаючи Halyk Bank, гарантують коректну обробку всіх статусів та повернень.
У цій статті ми детально розберемо архітектуру інтеграції, продемонструємо приклади коду для створення платежу та обробки callback, а також надамо рекомендації щодо типових помилок. Ви дізнаєтеся, як налаштувати двостадійні платежі та повернення, і як кешувати токен для надійної роботи. Інтеграція окупається за рахунок зниження ручної праці на 30% та прискорення обробки замовлень на 40%.
Інтеграція 1С-Бітрікс з Halyk Bank: від вибору способу до обробки платежів
Інтеграція 1С-Бітрікс з Halyk Bank: як вибрати спосіб підключення?
Halyk Bank надає кілька варіантів підключення: Halyk eCommerce (редирект), Halyk API (прямий прийом) та HalykPay. Нижче — порівняння за ключовими параметрами:
| Спосіб | Складність | PCI DSS | Час впровадження | Рекомендація |
|---|---|---|---|---|
| Halyk eCommerce (Redirect) | Низька | Не потрібен | 2-3 дні | Для більшості магазинів |
| Halyk API (Direct) | Висока | Потрібен | 5-7 днів | Для великих майданчиків |
| HalykPay | Середня | Не потрібен | 3-4 дні | Для мобільних додатків |
Для 90% казахстанських інтернет-магазинів оптимальний вибір — редиректна схема. Вона знімає відповідальність за зберігання даних карток і прискорює час виходу на ринок у 2 рази порівняно з прямим прийомом, а також коштує на 30% дешевше в інтеграції.
Чому варто обрати редиректну схему?
Редирект на платіжну форму банку знімає з магазину відповідальність за зберігання даних карток — не потрібно проходити аудит PCI DSS. Час впровадження скорочується на 40-50% порівняно з прямим прийомом. Крім того, така схема спрощує підтримку та оновлення платіжного модуля. Економія на комісії еквайрингу може досягати 0,5% від обороту.
Архітектура інтеграції
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'] ); Оновлення токена доступу
Токен доступу має обмежений термін життя. Рекомендується реалізувати його кешування та автоматичне оновлення. При отриманні HTTP 401 повторно запитуйте токен і повторюйте запит. Зберігайте обидва ідентифікатори рахунку: invoiceId (ваш) та id (внутрішній Halyk) — вони необхідні для повернень та верифікації.
Типові помилки новачків
Новачки часто не перевіряють верифікацію callback через додатковий API-запит, що призводить до фальшивих підтверджень. Друга помилка — відсутність кешування токена: при кожному запиті отримують новий токен, що збільшує час відповіді на 20-30%. Третя — не обробляють статус AUTHENTICATED при двостадійній схемі, через що гроші холдуються, але не списуються. Наш досвід показує, що ці проблеми зустрічаються у 70% проектів на старті.
Що входить в роботу
- Аналіз поточної логіки платежів на Бітрікс
- Проектування схеми інтеграції (редирект або прямий)
- Розробка модуля з обробниками токена, інвойсу, callback
- Налаштування двостадійних платежів (якщо потрібно)
- Реалізація повернень та кешування токена
- Тестування в тестовому та бойовому середовищі
- Документація та навчання вашої команди
- Гарантійна підтримка 30 днів
Терміни розробки
| Задача | Термін |
|---|---|
| Отримання токена + створення рахунку + callback | 2–3 дні |
| Двостадійні платежі | +1 день |
| Повернення | +1 день |
| Кешування токена + retry логіка | +0.5 дня |
| Тестування | 0.5–1 день |
Підсумковий термін — від 3 до 6 робочих днів. Вартість розраховується індивідуально після оцінки проекту, орієнтовно від 300 000 тенге. Отримайте консультацію — зв'яжіться з нами, і ми запропонуємо оптимальне рішення під ваш магазин. Ми маємо 5+ років досвіду та понад 50 успішних інтеграцій. Замовте інтеграцію — ми проведемо аудит вашого магазину і запропонуємо оптимальне рішення. Оцініть проект за 1 день — напишіть нам.
Офіційна документація Halyk Bank API доступна на сайті банку. Додатково: вивчіть офіційну документацію Halyk Bank для отримання актуальної інформації.