Halyk ePay на сайте: порядок интеграции и что проверить перед запуском

Интеграция Halyk ePay на сайт обычно состоит из пяти шагов: заключение договора на интернет-эквайринг, получение тестовых доступов, реализация создания платежа и приёма результата на сервере, прохождение тестовых сценариев и переход на рабочие реквизиты. Самые частые проблемы появляются не в самой форме оплаты, а в обработке уведомлений, статусов заказа и возвратов. Точные параметры запросов и форматы берите только из актуальной документации банка.

Общая схема платежа картой через сайт

Вне зависимости от деталей конкретного провайдера, схема интернет-эквайринга выглядит похоже.

1. Покупатель оформляет заказ, и сайт создаёт его у себя со статусом «ожидает оплаты».
2. Сервер сайта обращается к платёжному шлюзу и получает данные для оплаты: либо адрес платёжной страницы, либо параметры для виджета.
3. Покупатель вводит данные карты на стороне банка, а не на вашем сайте. Это важно для безопасности и для требований к хранению платёжных данных.
4. Банк сообщает результат двумя путями: перенаправляет покупателя на ваш адрес возврата и отправляет серверное уведомление на ваш адрес.
5. Сайт сверяет результат, меняет статус заказа, отправляет чек и запускает исполнение.

Ключевая мысль: доверять нужно серверному уведомлению и проверке статуса у шлюза, а не тому, что покупатель вернулся на страницу «успешно». Страницу возврата можно открыть вручную.

Подготовка: договор, доступы, тестовая среда

Раньше кода идёт организационная часть. Для подключения интернет-эквайринга банк запрашивает документы о бизнесе и данные о сайте. Требования к сайту (контакты, описание товаров и услуг, условия возврата, политика обработки данных) стоит выполнить заранее, чтобы заявка не зависла на проверке.

По условиям банка я не буду называть сроки и комиссии: они меняются и зависят от вашего договора. Что стоит выяснить у менеджера:

• есть ли тестовая среда и как получить доступы;
• какие способы оплаты доступны в вашем тарифе;
• как устроены возвраты и отмены, полные и частичные;
• как банк формирует выписки и реестры для сверки;
• как проходит переход с тестовых реквизитов на рабочие.

Всё, что вы услышали устно, зафиксируйте письменно или найдите в документации.

Реализация на стороне сервера

Если у вас самописный сайт на PHP, логику удобно разделить на несколько небольших частей.

• Создание платежа: формирует уникальный номер счёта или заказа, запрашивает у шлюза платёжную сессию, сохраняет её данные и статус.
• Приём серверного уведомления: проверяет подлинность запроса, находит заказ, обновляет статус.
• Страница возврата: показывает покупателю статус, предварительно уточнив его в базе или у шлюза.
• Запрос статуса: служебная функция, которая по номеру платежа спрашивает у шлюза текущее состояние. Она помогает, когда уведомление потерялось.
• Возвраты: функция, вызывающая операцию возврата и фиксирующая результат.

Секреты (ключи, пароли, токены) храните вне репозитория и вне публично доступного каталога, например в переменных окружения или конфигурационном файле с ограниченными правами. Подписывать и проверять запросы нужно ровно так, как указано в документации банка. Не пытайтесь угадать алгоритм: любое отличие означает отказ.

Небольшая заготовка таблицы для платежей:

CREATE TABLE payments (
  id            BIGINT AUTO_INCREMENT PRIMARY KEY,
  order_id      BIGINT NOT NULL,
  external_id   VARCHAR(64) NOT NULL,
  amount        DECIMAL(12,2) NOT NULL,
  status        VARCHAR(20) NOT NULL DEFAULT 'pending',
  created_at    DATETIME NOT NULL,
  updated_at    DATETIME NOT NULL,
  UNIQUE KEY uq_external (external_id)
);

Уникальный ключ по внешнему идентификатору помогает не создать платёж дважды и спокойно переживать повторные уведомления. Подробнее про это в статье об идемпотентности повторных уведомлений.

Что проверить в обработчике уведомлений

Это самая уязвимая часть интеграции, поэтому я проверяю её отдельно.

1. Подлинность: запрос действительно пришёл от банка (подпись, секрет, при необходимости адрес отправителя).
2. Соответствие суммы: сумма в уведомлении равна сумме заказа, а валюта ожидаемая.
3. Повторы: второе такое же уведомление не создаёт второй оплаты и не отправляет второй чек.
4. Порядок: уведомление «ошибка» не должно перезаписать уже успешный платёж.
5. Скорость ответа: обработчик быстро отвечает банку, тяжёлую работу вынесите в очередь или фоновое задание.
6. Журнал: каждое входящее уведомление записывается, чтобы спорную ситуацию можно было разобрать.

Больше о защите платёжных точек написано в статье про подпись запросов и журнал.

Чек-лист перед запуском

Перед переходом на рабочие реквизиты пройдите сценарии в тестовой среде и запишите результаты.

• Успешная оплата: статус заказа изменился, письмо клиенту ушло, менеджер увидел заказ.
• Отказ банка и ошибка карты: заказ не помечен оплаченным, клиенту предложено повторить.
• Закрытая вкладка во время оплаты: заказ остаётся в ожидании, платёж можно донести позже.
• Потерянное уведомление: служебный запрос статуса восстанавливает картину.
• Повторное уведомление: ничего не дублируется.
• Возврат полный и частичный, если поддерживаются вашим тарифом.
• Двойное нажатие на кнопку оплаты: не создаётся два платежа по одному заказу.
• Сроки жизни неоплаченного заказа: что происходит с ним через сутки.

Расширенный набор сценариев разобран в материале про тестирование платёжной интеграции.

Фискализация и сверка

Оплата картой на сайте обычно требует корректного оформления чека по правилам вашей деятельности. Как это делается, зависит от схемы: онлайн-касса, сервис фискализации, интеграция с учётной системой. Для казахстанских проектов это отдельный блок, о нём рассказывает статья про Webkassa, Regos и фискальные чеки. Вопросы налогового учёта задавайте бухгалтеру или юристу.

Для сверки заложите сопоставление платежей в вашей базе с реестрами банка по внешнему идентификатору и сумме. Если учёт ведётся в 1С, результат лучше загружать автоматически, а расхождения разбирать списком. Подход описан в статье об автоматической сверке платежей с 1С.

Типичные ошибки при подключении

За время работы с платёжными интеграциями я вижу одни и те же промахи. Рабочие ключи попадают в репозиторий вместе с кодом. Сумма берётся из параметров браузера, а не из заказа на сервере, и покупатель может её подменить. Статус заказа меняется по факту открытия страницы возврата. Обработчик уведомлений падает на непредвиденном поле и банк получает ошибку вместо подтверждения. Нет журнала, поэтому при споре невозможно показать, что приходило и что отвечал сайт.

Отдельная группа ошибок связана с окружениями: тестовые адреса остаются в рабочей конфигурации после запуска, а рабочие вызываются при тестировании. Разделите конфигурации и сделайте так, чтобы выбор окружения был явным и виден администратору.

Что подготовить на стороне бизнеса

Интеграция не ограничивается кодом. Заранее решите, кто ведёт переписку с банком, кто принимает платежи на стороне бухгалтерии, как обрабатываются возвраты и спорные операции, кто получает уведомления о проблемах. Опишите условия возврата и доставки на сайте простым языком: банк и покупатель ожидают их увидеть. Если нужны юридические формулировки оферты или политики конфиденциальности, их стоит согласовать с юристом.

Частые вопросы

Можно ли тестировать оплату на рабочем сайте реальной картой?

Это нежелательно: вы смешиваете тестовые и реальные данные, а возвраты имеют свои сроки и условия. Используйте тестовую среду и тестовые данные, которые предоставляет банк, а перед запуском сделайте минимальную контрольную оплату по согласованию с банком.

Что делать, если клиент оплатил, а заказ остался неоплаченным?

Проверьте журнал входящих уведомлений и запросите статус платежа у шлюза. Причина обычно в недоступном адресе уведомлений, неверной проверке подписи или ошибке в обработчике. Поэтому служебный запрос статуса и мониторинг доступности нужны сразу.

Нужен ли HTTPS для приёма уведомлений?

Да, защищённое соединение должно быть на всех адресах, связанных с платежами. Требования банка к сертификатам и адресам уточните в документации.

Сколько времени занимает интеграция?

Зависит от самого сайта, согласований с банком и объёма сценариев. Называть универсальные сроки некорректно, лучше оценивать после просмотра документации и состояния проекта.

Если нужна помощь с подключением, загляните на страницу об интеграциях платёжных систем или напишите в Telegram.