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

Ниже разбираем по шагам: что нужно от бизнеса, как устроена техническая схема, где обычно спотыкаются казахстанские компании и как сделать так, чтобы деньги доходили, а заказы не терялись.

Что такое Halyk ePay и кому он подходит

ePay (сайт epayment.kz) это сервис интернет-эквайринга Halyk Bank. Он принимает оплату картами Visa, Mastercard и UnionPay, а на сайте сервиса также заявлены Apple Pay, Samsung Pay и оплата по QR. Для приложения это значит, что клиент может заплатить картой любого казахстанского банка, а не только Halyk.

Halyk ePay хорошо подходит, если:

  • вы продаёте физические товары или услуги: доставка еды в Астане, магазин одежды в Алматы, запись в салон, билеты на мероприятие;
  • у вас уже есть расчётный счёт в Halyk Bank или вы готовы его открыть;
  • нужна оплата картой в дополнение к Kaspi, потому что часть клиентов платит картами других банков.

Важное ограничение: если вы продаёте цифровой контент (подписку на курсы, премиум-функции, внутриигровую валюту), Apple и Google требуют использовать их встроенные покупки. Эквайринг банка для таких продаж в приложении не подойдёт, иначе обновление отклонят на проверке.

Шаг 1. Договор с банком и документы

Заявку на подключение можно оставить на сайте Halyk Bank в разделе интернет-эквайринга или написать на [email protected]. Сам договор подписывается в отделении банка с менеджером. Точный пакет документов банк называет при обращении, он зависит от формы бизнеса (ИП или ТОО). Обычно готовьте:

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

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

Шаг 2. Тестовая среда

После одобрения вы получаете данные для интеграции: идентификаторы терминала и учётные данные для авторизации. У ePay есть отдельный тестовый контур со своими адресами. Например, на момент написания в документации указаны тестовый сервер авторизации test-epay-oauth.epayment.kz и тестовый скрипт платёжной формы на test-epay.epayment.kz. Боевые адреса другие, поэтому переключение между тестом и продом лучше вынести в настройки сервера, а не зашивать в код.

В тестовой среде проверяйте не только успешную оплату, но и отказ, отмену, повторную попытку, закрытие формы на середине. Именно эти сценарии потом ломаются у реальных клиентов.

Шаг 3. Схема интеграции: как деньги проходят через приложение

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

  1. Клиент оформляет заказ в приложении, приложение отправляет его на ваш сервер.
  2. Сервер создаёт заказ со своим номером счёта (invoiceId) и суммой.
  3. Сервер запрашивает у ePay токен доступа по протоколу OAuth (тип client_credentials). По документации токен живёт ограниченное время, поэтому его получают перед каждой оплатой, а не хранят неделями.
  4. Сервер отдаёт приложению только то, что нужно для показа формы: токен, номер счёта, сумму.
  5. Приложение открывает платёжную форму ePay: через мобильный SDK банка или через встроенный браузер (WebView) со страницей оплаты, которая вызывает функцию halyk.pay().
  6. После оплаты ePay отправляет уведомление на ваш адрес postLink. Сервер проверяет его, помечает заказ оплаченным и сообщает приложению.
  7. Если уведомление не пришло, сервер запрашивает статус транзакции через отдельный метод проверки статуса.

Подробнее о том, как строится серверная часть, мы писали в статье про бэкенд для мобильного приложения.

SDK или страница оплаты в WebView

Вариант Плюсы Минусы
Мобильный SDK ePay (iOS, Android) Нативный вид, меньше переходов, удобнее для клиента Нужно следить за версиями SDK, во Flutter и React Native понадобится обёртка
Платёжная страница в WebView Одна реализация на iOS и Android, быстрый старт, те же правила, что на сайте Нужно аккуратно ловить возврат в приложение и 3-D Secure
Оплата в браузере по ссылке Самый простой вариант Клиент уходит из приложения, часть заказов теряется

Для большинства приложений на Flutter мы начинаем с WebView: это быстрее и надёжнее. SDK имеет смысл, когда платежей много и важна каждая доля конверсии.

Сроки и стоимость

Сроки складываются из двух частей. Первая зависит от банка: рассмотрение заявки, подписание договора, выдача доступов. Её точную длительность уточняйте у менеджера Halyk Bank. Вторая зависит от разработки: серверная часть, экран оплаты, обработка уведомлений, возвраты, тестирование. Если приложение уже работает и в нём есть корзина, интеграция одного способа оплаты обычно занимает от одной до трёх недель.

Комиссия банка указана на сайте epayment.kz и зависит от того, какой банк выпустил карту клиента. На момент написания там заявлены разные ставки для карт Halyk и карт других банков, без абонентской платы. Перед запуском сверьте тарифы в своём договоре: они могут отличаться от публичных.

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

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

  1. Тестовые оплаты прошли по всем сценариям: успех, отказ, отмена, повтор, закрытие формы.
  2. Сервер получает уведомления postLink на боевом адресе с HTTPS, и они пишутся в журнал.
  3. Есть фоновая проверка статуса для заказов, по которым уведомление не пришло за разумное время.
  4. Клиент видит понятный экран «Оплата прошла» или «Не удалось оплатить» с кнопкой повторить.
  5. Менеджер видит статус оплаты в админ-панели и может оформить возврат.
  6. Боевые ключи хранятся в настройках сервера, а не в репозитории.

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

Частые ошибки казахстанских компаний

  • Секретный ключ внутри приложения. Его легко достать из сборки. Любые запросы с client_secret делает только сервер.
  • Заказ помечается оплаченным по сигналу из приложения. Клиент закрыл форму, связь пропала, а в базе «оплачено». Статус меняет только сервер по уведомлению банка или по запросу статуса.
  • Нет проверки уведомления. Адрес postLink открыт в интернет. Сверяйте сумму, номер счёта и контрольные поля из ответа, иначе кто-то может прислать поддельное «успешно».
  • Повторный номер счёта. Клиент нажал «оплатить» дважды, и получилось два списания или ошибка. Номер счёта должен быть уникальным для каждой попытки.
  • Забыли про возвраты. Отмена заказа и возврат денег нужны с первого дня, особенно в доставке.
  • Пытаются продавать подписку через банк. Цифровые товары в приложении проходят через покупки Apple и Google, иначе отказ на проверке.

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

Halyk ePay и Kaspi: нужны ли оба

В Казахстане многие клиенты привыкли платить через Kaspi, поэтому часто разумно подключать и то, и другое. Kaspi закрывает тех, кто живёт в экосистеме Kaspi, ePay закрывает оплату картами любых банков и Apple Pay. Как устроено подключение Kaspi, мы разбирали отдельно: интеграция Kaspi Pay в приложение. Архитектура на сервере при этом одна: единая таблица заказов и платежей, а каждый провайдер подключается отдельным модулем.

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

Можно ли подключить Halyk ePay без сайта, только для приложения?

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

Будут ли работать карты других банков, а не только Halyk?

Да, ePay принимает карты Visa, Mastercard и UnionPay любых банков. Комиссия для карт Halyk и других банков может отличаться, смотрите тарифы в своём договоре.

Можно ли продавать подписку в приложении через Halyk ePay?

Если это цифровой контент, который потребляется в самом приложении, Apple и Google требуют встроенные покупки. Эквайринг банка подходит для физических товаров и услуг вне приложения.

Сколько времени занимает подключение?

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

Нужен ли свой сервер для оплаты через ePay?

Да. Токен на оплату и проверка уведомлений должны идти через ваш сервер, иначе секретные ключи окажутся в приложении, а статус оплаты нельзя будет проверить надёжно.

Подключим оплату под ключ

Команда applications.kz подключает Halyk ePay, Kaspi и другие способы оплаты в приложения на iOS, Android и Flutter: серверная часть, экран оплаты, уведомления, возвраты и тестирование. Если приложения ещё нет, сделаем его целиком, подробнее на странице разработки мобильных приложений. Напишите нам через форму контактов или в WhatsApp +7 707 928 13 15, смету подготовим бесплатно за 24 часа.