EPay

Продукт: Shelter Cloud | Уровень: Shelter | Статус: Stable

ID системы: 24

Описание

Интеграция с платёжной системой EPay (Kazakhstan) — казахстанская платёжная система от Halyk Bank. Использует OAuth 2.0 для аутентификации.

Настройка в Shelter Cloud

Параметры учётной записи настраиваются через PrivateSettings:

Параметр	Описание
ClientId	Идентификатор клиента OAuth
ClientSecret	Секрет клиента OAuth
ShopId	ID магазина
AccountId	ID аккаунта
Currency	Валюта: `KZT`, `USD`, `EUR`, `RUB`, `GBP`, `CNY`
IsTest	Тестовый режим (`true` / `false`)

Конфигурация сервиса (appsettings.json)

Параметр	Описание
IPWhiteList	Список разрешённых IP для callback. Доступ: отдел разработки

API Endpoints

OAuth

Среда	URL
Test	`https://test-epay-oauth.epayment.kz/oauth2/token`
Production	`https://epay-oauth.homebank.kz/oauth2/token`

Платежи

Среда	URL
Test	`https://test-epay-api.epayment.kz/invoice`
Production	`https://epay-api.homebank.kz/invoice`

Callback

URL для callback: https://cloud.shelter.ru/EPay/Result

Алгоритм подписи

Алгоритм: MD5

secret_hash = MD5(accountId + ";" + invoiceId + ";" + amount + ";" + clientSecret)

Процесс оплаты

Клиент нажимает «Оплатить»
Получение OAuth токена
Формирование данных платежа с подписью
Отправка запроса на EPay API
Редирект клиента на страницу оплаты
После оплаты — callback на /Result
Проверка подписи и запись платежа

Поддерживаемые валюты

Код	Валюта
KZT	Казахстанский тенге
USD	Доллар США
EUR	Евро
RUB	Российский рубль
GBP	Британский фунт
CNY	Китайский юань

Мониторинг (Zabbix)

Health check URL: https://cloud.shelter.ru/EPay/

Логирование

Все события логируются в Graylog (channel: EPay).

Примеры сообщений при callback

Получен callback:

Оплата: POST /EPay/Result
Data: {"accountId":"ACC001","invoiceId":"INV-001","amount":5000.00,"signature":"abc123"}

Успешная оплата:

Оплата успешно: 100

Ошибка подписи:

Ошибка оплаты: Сформированная сигнатура 'xyz789' не совпадает с полученной 'abc123'

IP не в whitelist:

Ошибка оплаты: не допустимый ip адрес

Устранение неполадок

Ошибка «Invalid token»

Причина: Истёк срок действия access_token.

Решение: Получите новый токен перед каждым платежом (действителен 1 час).

Ошибка «Invalid secret_hash»

Причина: Неправильно сформирована подпись.

Решение:

Проверьте порядок параметров: accountId;invoiceId;amount;secret
Убедитесь, что amount с точкой как разделителем
Проверьте ClientSecret

Invoice already exists (code 2139)

Причина: invoiceId уже использовался.

Решение: Используйте уникальный invoiceId для каждого платежа.

Callback не приходит