Прием платежей Kapital Bank в 1С-Битрикс: интеграция для Азербайджана

Подключаем платежи Kapital Bank к 1С-Битрикс

Если ваш интернет-магазин на 1С-Битрикс не принимает карты Kapital Bank — крупнейшего банка Азербайджана с долей рынка онлайн-платежей более 40%, — вы теряете до 30% покупателей. Интеграция с этим банком не просто добавляет способ оплаты, но и повышает доверие: знакомый логотип на странице оформления заказа увеличивает конверсию на 15–20%. Мы с 2013 года разрабатываем платёжные модули для Битрикса и реализовали более 50 проектов интеграции платежных систем. За 3–5 дней мы подключаем HPP Kapital Bank, чтобы ваши клиенты из Азербайджана могли платить картами Visa и Mastercard. Всё, что нужно от вас, — Merchant ID и секретный ключ, остальное берём на себя. Получите консультацию в течение дня.

Источник: Wikipedia, Kapital Bank

Способы подключения Kapital Bank

Банк предлагает два варианта: HPP (Hosted Payment Page) и Direct API. HPP — стандартный способ для 95% мерчантов: покупатель перенаправляется на страницу банка, вводит данные карты, а сайт получает callback с результатом. Этот вариант не требует сертификации PCI DSS — безопасность полностью на стороне банка. Direct API подразумевает прямую передачу карточных данных через API, что требует PCI DSS и используется редко (мобильные приложения, нестандартные сценарии). Для типового магазина HPP в 5 раз быстрее внедряется и не накладывает лишних бюрократических ограничений. Стоимость интеграции HPP на 30–40% ниже, чем Direct API, а конверсия выше за счёт доверия к банковской странице.

Как работает HPP-интеграция с Kapital Bank?

1. Покупатель выбирает оплату картой на сайте.
2. Система формирует XML-запрос с суммой (в тиинах: 1 AZN = 100 qəpik) и отправляет его на эндпоинт банка.
3. В ответ банк возвращает OrderId и SessionId — на их основе строится URL редиректа на HPP.
4. Покупатель вводит данные карты на странице банка.
5. После успеха банк отправляет callback на ApproveURL — наш обработчик проверяет статус через GetOrderStatus и меняет статус заказа.

Мы реализуем кастомный обработчик на базе \Bitrix\Sale\PaySystem\ServiceHandler с методами initiatePay(), processRequest() и refund(). Подробности — в структуре запроса ниже.

Структура запроса к API банка

При инициации платежа формируется POST-запрос к эндпоинту:

• Тест: https://tstpg.kapitalbank.az/api/order/
• Продакшн: https://pg.kapitalbank.az/api/order/

Тело — XML:

<TKKPG>
  <Request>
    <Operation>CreateOrder</Operation>
    <Language>RU</Language>
    <Order>
      <OrderType>Purchase</OrderType>
      <Merchant>MERCHANT_ID</Merchant>
      <Amount>15000</Amount>
      <Currency>944</Currency><!-- AZN = 944 по ISO 4217 -->
      <Description>Заказ №12345</Description>
      <ApproveURL>https://site.az/payment/success/</ApproveURL>
      <CancelURL>https://site.az/payment/cancel/</CancelURL>
      <DeclineURL>https://site.az/payment/fail/</DeclineURL>
    </Order>
  </Request>
</TKKPG>

Ответ содержит OrderId и SessionId, на основе которых формируется URL редиректа. После оплаты банк стучит на ApproveURL с этими же параметрами. В processRequest() мы делаем дополнительный запрос GetOrderStatus — callback может не содержать подписи, поэтому доверять ему напрямую нельзя.

Обработка возвратов (Refund)

Kapital Bank поддерживает два типа возвратов:

• Reverse — полный возврат в день транзакции.
• Refund — частичный или поздний.

В обработчике реализуется метод refund(), который вызывается из административной части Битрикс при смене статуса заказа на «Возврат». В таблице b_sale_payment поле PS_INVOICE_ID хранит OrderId от банка — он и используется для инициации возврата.

Что делать, если callback не доходит?

Иногда платеж проходит, но статус заказа не обновляется. Вот типичные причины:

• Callback-URL недоступен извне (проверьте файрвол и настройки веб-сервера).
• IP банка заблокирован.
• XML-запрос отправлен в неправильной кодировке.

Мы всегда добавляем логирование входящих запросов на callback-эндпоинт, чтобы быстро найти проблему. В наших проектах после тестирования срок наработки — 3–5 дней, и за это время мы гарантируем стабильную работу обработчика.

Тестирование и типичные проблемы

Частая ошибка — несоответствие кодировки XML (банк ожидает UTF-8 без BOM). При работе через curl в PHP обязательно выставляем Content-Type: text/xml; charset=utf-8.

Пошаговая настройка обработчика Kapital Bank

1. Получите Merchant ID и секретный ключ в банке.
2. В административной панели Битрикс перейдите в Магазин → Платёжные системы и создайте новую систему.
3. Выберите обработчик KapitalBank и укажите Merchant ID, пароль, режим (тест/продакшн).
4. Установите валюту по умолчанию — AZN.
5. Настройте статусы заказа для успешной оплаты и ошибки.
6. Проверьте callback-URL: он должен быть доступен извне и возвращать HTTP 200.
7. Выполните тестовый платёж с использованием тестовой карты.

Компонент sale.order.ajax на сайте не требует изменений — перенаправление на HPP обрабатывается стандартным механизмом Битрикс через BX_PAYMENT_REDIRECT.

Как избежать ошибок при интеграции?

• Всегда проверяйте сумму в тиинах (умножьте AZN на 100).
• Убедитесь, что XML отправляется с кодировкой UTF-8 без BOM.
• Добавьте логирование входящих callback-запросов для отладки.
• Не доверяйте callback напрямую — делайте дополнительный запрос GetOrderStatus.
• Настройте мониторинг статусов заказов: при сбое callback-уведомления заказ останется в статусе «ожидание оплаты».

Сроки и состав работ

Получите консультацию по вашему проекту — мы оценим сложность и расскажем детали. Свяжитесь с нами, чтобы заказать интеграцию под ключ. Начните принимать платежи через Kapital Bank уже через 3 дня.