Інтеграція 1С-Бітрікс з платіжною системою iPay (Білорусь)

При підключенні iPay до магазину на Бітрікс ми часто стикаємося з типовими помилками: неправильний розрахунок суми в копійках, збій сповіщень через пропущену перевірку підпису, конфлікти з кешуванням на сторінці успіху. У цій статті розберемо, як цього уникнути, і покажемо робочий приклад інтеграції з нуля. Наш досвід показує: підключення iPay під ключ займає від 5 до 10 робочих днів, включаючи отримання тестового доступу, розробку кастомного обробника та фіскалізацію за 54-ФЗ (якщо потрібно). Ми гарантуємо коректну обробку всіх статусів та повернень, а також повну документацію для вашої команди.

iPay — білоруський платіжний агрегатор від компанії «Дежур», що працює на базі процесингу НКФО «Открытое акционерное общество «Небанковская кредитно-финансовая организация». Шлюз підтримує картки Visa, Mastercard, Белкарт та платежі через ЄРІП. Для малого та середнього бізнесу в Білорусі iPay часто виступає альтернативою прямому підключенню до банків — зі спрощеною документацією та швидким onboarding.

Які варіанти інтеграції iPay підтримує?

iPay надає два варіанти інтеграції:

Hosted Payment Page — покупець перенаправляється на сторінку iPay, обирає спосіб оплати, платить. Магазин отримує сповіщення. Мінімальні вимоги до безпеки на стороні магазину — PCI DSS не потрібен.

API-інтеграція — дані картки приймаються формою на сайті магазину та передаються в iPay. Вимагає PCI DSS або токенізації через JS-бібліотеку iPay.

Для більшості впроваджень на Бітрікс використовується Hosted Page як більш простий та безпечний варіант.

Як реалізувати кастомний обробник iPay на Бітрікс?

Офіційного модуля 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": "uk" } 

Сума передається в білоруських копійках (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": "2023-06-15T14:32:11Z", "signature": "sha256_hash_here" } 

Верифікація підпису — SHA-256 від рядка payment_id + order_id + amount + currency + shop_secret. Без перевірки підпису будь-хто може відправити фальшиве сповіщення про оплату. Алгоритм SHA-256 описаний у Wikipedia. Джерело: Вікіпедія

Статуси: 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 робочих днів.

Що входить у нашу роботу з інтеграції iPay?

• Розробка кастомного платіжного обробника для Бітрікс.
• Налаштування сповіщень та перевірки підпису.
• Реалізація повернень через API.
• Інтеграція з 1С (опціонально) для синхронізації статусів.
• Тестування в пісочниці та на бойовому оточенні.
• Документація та передача доступів.

Ми оцінюємо проєкт безкоштовно — напишіть нам, і ми підготуємо точний кошторис. Наші спеціалісти мають 5-річний досвід роботи з Бітрікс та понад 50 успішних інтеграцій платіжних систем.