Интеграция 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.

Сроки