Підключаємо платежі 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?
- Покупець обирає оплату карткою на сайті.
- Система формує XML-запит із сумою (у тіїнах: 1 AZN = 100 qəpik) і надсилає його на ендпоінт банку.
- У відповідь банк повертає
OrderIdтаSessionId— на їх основі будується URL редиректу на HPP. - Покупець вводить дані картки на сторінці банку.
- Після успіху банк надсилає 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 днів, і за цей час ми гарантуємо стабільну роботу обробника.
Тестування та типові проблеми
Таблиця тестування
| Етап | Що перевіряємо |
|---|---|
| Створення замовлення | Коректність суми (у тіїнах — 1 AZN = 100 qəpik), Currency = 944 |
| Редирект на HPP | URL містить обидва параметри: ORDERID і SESSIONID |
| Callback обробка | Статус замовлення змінюється, дублюючі виклики ігноруються |
| Тестові картки | Visa 4169741330151124, CVC 119, будь-який термін у майбутньому |
| Продакшн | Зміна endpoint та credentials, перевірка SSL-сертифіката |
Часта помилка — невідповідність кодування XML (банк очікує UTF-8 без BOM). При роботі через curl у PHP обов'язково виставляємо Content-Type: text/xml; charset=utf-8.
Покрокове налаштування обробника Kapital Bank
- Отримайте Merchant ID та секретний ключ у банку.
- В адміністративній панелі Бітрікс перейдіть до Магазин → Платіжні системи та створіть нову систему.
- Виберіть обробник
KapitalBankта вкажіть Merchant ID, пароль, режим (тест/продакшн). - Встановіть валюту за замовчуванням — AZN.
- Налаштуйте статуси замовлення для успішної оплати та помилки.
- Перевірте callback-URL: він має бути доступний ззовні та повертати HTTP 200.
- Виконайте тестовий платіж з використанням тестової картки.
Компонент sale.order.ajax на сайті не потребує змін — перенаправлення на HPP обробляється стандартним механізмом Бітрікс через BX_PAYMENT_REDIRECT.
Як уникнути помилок при інтеграції?
- Завжди перевіряйте суму в тіїнах (помножте AZN на 100).
- Переконайтеся, що XML надсилається з кодуванням UTF-8 без BOM.
- Додайте логування вхідних callback-запитів для налагодження.
- Не довіряйте callback напряму — робіть додатковий запит
GetOrderStatus. - Налаштуйте моніторинг статусів замовлень: при збої callback-повідомлення замовлення залишиться в статусі «очікування оплати».
Терміни та склад робіт
| Масштаб проєкту | Склад | Термін |
|---|---|---|
| Стандартний магазин | Модуль HPP + тестування + документація | 3–5 днів |
| З частковими поверненнями | + метод Refund, UI в адмінці | 5–7 днів |
| Кілька магазинів (мультисайт) | + налаштування під кожен сайт | +1–2 дні |
Отримайте консультацію по вашому проєкту — ми оцінимо складність і розповімо деталі. Зв'яжіться з нами, щоб замовити інтеграцію під ключ. Почніть приймати платежі через Kapital Bank вже через 3 дні.