При интеграции 1С-Битрикс с Halyk Bank разработчики часто сталкиваются с ошибками в обработке callback-уведомлений и некорректным кешированием токенов доступа. Это приводит к потере заказов и разрыву цепочки оплаты. Часто callback приходит с задержкой или не приходит вовсе, что вызывает двойные списания и недовольство покупателей. Разберём, как правильно настроить взаимодействие и избежать типовых проблем.
Halyk Bank — крупнейший банк Казахстана, предоставляет интернет-эквайринг через платёжный шлюз Halyk eCommerce (ранее HomeBank). Шлюз принимает карты Visa, Mastercard, American Express, а также оплату через мобильное приложение HalykPay. Интеграция с Битрикс реализуется через стандартный платёжный модуль с обработчиками на PHP. Наш многолетний опыт разработки на Битрикс и десятки успешных кейсов интеграции с платёжными шлюзами, включая Halyk Bank, гарантируют корректную обработку всех статусов и возвратов. Мы имеем сертификаты Битрикс и большой опыт в разработке модулей.
В этой статье мы подробно разберём архитектуру интеграции, продемонстрируем примеры кода для создания платежа и обработки callback, а также дадим рекомендации по типовым ошибкам. Вы узнаете, как настроить двухстадийные платежи и возвраты, и как кэшировать токен для надёжной работы. Интеграция окупается за счёт снижения ручного труда на 30% и ускорения обработки заказов.
Интеграция 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 раза по сравнению с прямым приёмом.
Почему стоит выбрать редиректную схему?
Редирект на платёжную форму банка снимает с магазина ответственность за хранение данных карт — не нужно проходить аудит 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 рабочих дней. Стоимость рассчитывается индивидуально после оценки проекта. Получите консультацию — свяжитесь с нами, и мы предложим оптимальное решение под ваш магазин. Закажите интеграцию — мы проведём аудит вашего магазина и предложим оптимальное решение. Оцените проект за 1 день — напишите нам.
Официальная документация Halyk Bank API доступна на сайте банка. Дополнительно: изучите официальную документацию Halyk Bank для получения актуальной информации.