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

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

EasyPay — білоруський платіжний сервіс, що працює через мережу терміналів та інтернет-еквайринг. Особливість EasyPay полягає в розвиненій мережі фізичних терміналів по всій Білорусі: покупець може оформити замовлення онлайн і оплатити готівкою в найближчому терміналі EasyPay — це актуально для аудиторії, яка не використовує банківські картки онлайн. Для Бітрікс-магазину це окрема платіжна система в модулі sale з характерною логікою «відкладеної оплати».

Архітектура EasyPay для інтернет-магазинів

EasyPay надає два режими роботи для e-commerce:

Карткова оплата онлайн — стандартний еквайринг. Покупець вводить дані картки на платіжній сторінці EasyPay, гроші списуються одразу. Сповіщення надходить на webhook магазину.

Оплата через термінал — магазин створює рахунок, покупець отримує унікальний код платежу, оплачує в терміналі EasyPay. Нотифікація надходить із затримкою від кількох хвилин до кількох годин залежно від завантаженості мережі терміналів.

API-ендпоінт: https://checkout.easypay.by/api/ (продакшн), https://sandbox.easypay.by/api/ (тест).

Реалізація обробника в Бітрікс

Розташування: /local/php_interface/include/sale_payment/easypay_belarus/

Ініціалізація платежу — POST до /api/v1/invoice:

{
  "serviceId": "YOUR_SERVICE_ID",
  "accountNo": "BXORDER_45678",
  "amount": {
    "value": 7850,
    "currency": "BYN"
  },
  "info": "Замовлення №45678",
  "returnUrl": "https://shop.by/personal/order/detail/45678/",
  "notifyUrl": "https://shop.by/bitrix/tools/sale_ps_result.php",
  "expiredAt": "2024-12-20T18:00:00+03:00"
}

Сума — в копійках BYN. serviceId присвоюється при підключенні до EasyPay.

У відповідь надходить об'єкт з invoiceId та або paymentUrl (для онлайн-оплати карткою), або paymentCode (код для терміналу). Залежно від обраного режиму обробник або перенаправляє на paymentUrl, або показує покупцю paymentCode та інструкцію.

Відображення коду для терміналу

Екран після оформлення замовлення при оплаті через термінал повинен містити:

• Унікальний код платежу великим шрифтом
• Інструкцію: «Термінал EasyPay → Оплата послуг → Код платежу → введіть {код}»
• Карту з найближчими терміналами (EasyPay надає API для геолокації терміналів)
• Термін дії коду та дедлайн оплати

Шаблон платіжної системи в Бітрікс (template/) відповідає за цей екран. Якщо шаблон не доопрацювати, покупець побачить стандартний екран «Очікування оплати» без жодних інструкцій — часта причина дзвінків до підтримки.

Обробка нотифікацій

EasyPay надсилає POST на notifyUrl при успішній оплаті:

{
  "invoiceId": "ep_inv_112233",
  "accountNo": "BXORDER_45678",
  "status": "PAID",
  "amount": 7850,
  "currency": "BYN",
  "paidAt": "2024-12-19T15:22:41+03:00",
  "paymentMethod": "TERMINAL",
  "sign": "hmac_sha256_value"
}

paymentMethod може бути CARD, TERMINAL, ERIP. Незалежно від методу логіка обробки однакова, але статус замовлення можна фіксувати по-різному (наприклад, для термінальних платежів ставити «Оплата через термінал» у коментарі).

Верифікація sign — HMAC-SHA256 від рядка invoiceId + accountNo + amount + currency + secret.

Особливість: прострочені рахунки

Термінальні платежі часто прострочені — покупець забуває оплатити. EasyPay надсилає нотифікацію status: EXPIRED після закінчення expiredAt. У Бітрікс потрібно передбачити обробку цього статусу: автоматично скасовувати неоплачені замовлення або залишати їх менеджеру на ручне вирішення.

Для великих магазинів зручний cron-скрипт, що раз на годину перевіряє всі замовлення в статусі «Очікування оплати» старші N годин і викликає API EasyPay (GET /api/v1/invoice/{invoiceId}) для актуалізації статусу.

Реальний кейс: затримка нотифікації

Магазин електроніки, пікові дні — свята. Скарги: замовлення не підтверджуються одразу після оплати через термінал, покупець нервує. Діагностика: мережа терміналів EasyPay надсилала нотифікації із затримкою до 40 хвилин у період високого навантаження. Рішення: на сторінці після замовлення додати JS-поллінг статусу кожні 30 секунд через власний AJAX-ендпоінт, що викликає EasyPay API GET /api/v1/invoice/{invoiceId}. При отриманні статусу PAID — оновлювати сторінку без очікування webhook.

Терміни