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

Інтеграція 1С-Bitrix з платіжною системою Kapital Bank (Азербайджан)

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

Як працює платіжний шлюз Kapital Bank

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

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

Для більшості проектів на 1С-Bitrix використовується HPP: це простіше у супровіді та не накладає додаткові вимоги щодо безпеки.

Модуль оплати в 1С-Bitrix

Платіжна система в Bitrix підключається через компонент 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() в обробнику — він викликається з адміністративної частини Bitrix при зміні статусу замовлення на «Повернення».

У таблиці 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 обробляється стандартним механізмом Bitrix через BX_PAYMENT_REDIRECT.

Терміни та склад робіт