Интеграция 1С-Битрикс с платежной системой Kapital Bank (Азербайджан)

Интеграция 1С-Битрикс с платежной системой Kapital Bank (Азербайджан)

Kapital Bank — один из крупнейших банков Азербайджана, предоставляющий платёжный шлюз для интернет-эквайринга. Интеграция с 1С-Битрикс позволяет принимать оплату картами Visa, Mastercard и местными инструментами (карты Kapital Bank) прямо на сайте, не перенаправляя покупателя на сторонние страницы без необходимости.

Как работает платёжный шлюз Kapital Bank

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

• Hosted Payment Page (HPP). Покупатель перенаправляется на страницу банка, где вводит данные карты. Сайт получает обратный callback с результатом транзакции. Минимальные требования к PCI DSS на стороне мерчанта.
• Direct API (e-Commerce). Данные карты передаются напрямую через API банка. Требует сертификации PCI DSS SA или SAQ D. Используется редко — в основном для мобильных приложений и специфических флоу.

Для большинства проектов на 1С-Битрикс используется HPP: он проще в сопровождении и не накладывает дополнительных требований по безопасности.

Модуль оплаты в 1С-Битрикс

Платёжная система в Битрикс подключается через компонент sale.payment. Для Kapital Bank создаётся кастомный обработчик платёжной системы — PHP-класс, унаследованный от \Bitrix\Sale\PaySystem\ServiceHandler. Основные методы, которые реализуются:

• initiatePay() — формирует запрос к API банка, получает orderId и sessionId, строит URL редиректа на HPP.
• processRequest() — обрабатывает входящий callback (HTTP POST или GET от банка), верифицирует подпись, меняет статус заказа.
• isPaymentExpired() — проверяет истечение сессии оплаты (обычно 15–20 минут для Kapital Bank).

Параметры подключения хранятся в таблице b_sale_pay_system_action (настройки обработчика): MERCHANT_ID, SECRET_KEY, ENVIRONMENT (test/prod).

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

При инициации платежа формируется запрос к эндпоинту 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 вида https://pg.kapitalbank.az/...?ORDERID=...&SESSIONID=....

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

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

Kapital Bank поддерживает возвраты через операцию Reverse (полный возврат в день транзакции) и Refund (частичный или поздний). Реализуется метод refund() в обработчике — он вызывается из административной части Битрикс при смене статуса заказа на «Возврат».

В таблице b_sale_payment хранится поле PS_INVOICE_ID — это OrderId от банка, который используется для инициации возврата.

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

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

Что настраивается в административной панели

В разделе Магазин → Платёжные системы создаётся новая система с обработчиком KapitalBank. Администратор заполняет:

• Merchant ID и пароль (выдаёт банк)
• Режим работы (тест / продакшн)
• Валюта по умолчанию (AZN)
• Статусы заказа при успешной оплате и ошибке

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

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