Інтеграція 1С-Бітрікс з платіжною системою iPay (Білорусь)
iPay — білоруський платіжний агрегатор від компанії «Дежур», що працює на базі процесингу небанківської кредитно-фінансової організації. Шлюз підтримує картки Visa, Mastercard, Белкарт та платежі через ЄРІР. Для малого і середнього бізнесу в Білорусі iPay часто виступає альтернативою прямому підключенню до банків — зі спрощеною документацією та швидким onboarding.
Як працює iPay
iPay надає два варіанти інтеграції:
Hosted Payment Page — покупець перенаправляється на сторінку iPay, обирає спосіб оплати та платить. Магазин отримує сповіщення. Мінімальні вимоги до безпеки на стороні магазину — PCI DSS не потрібен.
API-інтеграція — дані картки приймаються формою на сайті магазину та передаються до iPay. Потребує PCI DSS або токенізації через JS-бібліотеку iPay.
Для більшості впроваджень на Бітрікс використовується Hosted Page як простіший і безпечніший варіант.
Ендпоінт: https://api.ipay.by/ (бойове середовище), https://sandbox.ipay.by/ (тест).
Технічна інтеграція з Бітрікс
Офіційного модуля iPay на Маркетплейсі Бітрікс немає. Реалізується як кастомний обробник у /local/php_interface/include/sale_payment/ipay_belarus/.
Ініціалізація платежу — POST-запит до /api/v1/payments:
{
"shop_id": "YOUR_SHOP_ID",
"order_id": "BXORDER_12345",
"amount": 5990,
"currency": "BYN",
"description": "Замовлення №12345 у магазині Example",
"success_url": "https://yourshop.by/thank-you/?order=12345",
"fail_url": "https://yourshop.by/payment-error/?order=12345",
"notify_url": "https://yourshop.by/bitrix/tools/sale_ps_result.php",
"lang": "ru"
}
Сума передається в білоруських копійках (BYN × 100). iPay повертає payment_id та payment_url — на останній виконується редирект покупця.
Обробка сповіщень
iPay надсилає POST на notify_url при зміні статусу платежу. Тіло сповіщення:
{
"payment_id": "ipay_txn_98765",
"order_id": "BXORDER_12345",
"status": "PAID",
"amount": 5990,
"currency": "BYN",
"paid_at": "2024-06-15T14:32:11Z",
"signature": "sha256_hash_here"
}
Верифікація підпису — SHA-256 від рядка payment_id + order_id + amount + currency + shop_secret. Без перевірки підпису будь-хто може надіслати фальшиве сповіщення про оплату.
Статуси: PAID (оплачено), FAILED (помилка), CANCELLED (скасовано), EXPIRED (сплинув термін).
Термін дії платіжної сесії
За замовчуванням iPay дає покупцю 15 хвилин на завершення оплати. Після закінчення сесія закривається зі статусом EXPIRED. У Бітрікс це означає, що обробник повинен вміти працювати з таймаутами: при отриманні EXPIRED — повідомити покупця та запропонувати нову спробу без створення дублюючого замовлення.
Термін можна збільшити до 60 хвилин через параметр expire_at у запиті створення платежу — корисно для B2B-замовлень, де рішення про покупку приймається довше.
Повернення через API
iPay підтримує повернення через API: POST до /api/v1/payments/{payment_id}/refund з параметрами amount (часткове або повне повернення) та reason. З адміністративної частини Бітрікс це можна реалізувати як кнопку «Повернення» на сторінці замовлення — метод ProcessRequestRefund обробника викликає API та оновлює статус платежу.
Реальний кейс: конфлікт з кешуванням сторінки
Білоруський інтернет-магазин дитячих товарів. Після успішної оплати через iPay покупці іноді бачили сторінку з реквізитами старого замовлення іншого користувача. Причина: сторінка «дякуємо за замовлення» кешувалася nginx, і при редиректі з success_url повертався кешований відповідь. Рішення: додати заголовок Cache-Control: no-store, no-cache для URL сторінок замовлення та переконатися, що параметр ?order= читається динамічно з Бітрікс-сесії, а не з URL.
Тестування
У тестовому середовищі iPay (sandbox.ipay.by) тестові картки публікуються в особистому кабінеті розробника. Для ЄРІР-оплати в тесті використовується емулятор — нотифікація приходить автоматично через 30 секунд після створення рахунку.
Терміни підключення: отримання тестового доступу — 1–2 дні. Розробка обробника — 2–3 дні. Бойове підключення з перевіркою документів компанії — 5–10 робочих днів.