Платежная страница, оплата посредством HalykID

Перед началом работы вам следует обратиться по адресу halykid@halykbank.kz для получения тестовых данных,тестового приложения и внедрения процесса получения кросс-авторизационного ключа homebankCasKey, который будет использоваться для дальнейшей передачи в систему ePay.

При регистрации вам будут выданы данные, которые нужно будет использовать при проведении платежа:


TerminalID	Идентификатор магазина
ClientID	Идентификатор клиента
ClientSecret	Секретный ключ

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

TEST URL POST https://test-epay-oauth.epayment.kz/oauth2/token
PROD URL POST https://epay-oauth.homebank.kz/oauth2/token

Запрос

Body: form-data

grant_type: 	"client_credentials"
scope: 			" webapi usermanagement email_send verification statement statistics payment"
client_id: 		"test"
client_secret: 	"yF587AV9Ms94qN2QShFzVR3vFnWkhjbAK3sG"
invoiceID: 		"000000001"
secret_hash: "HelloWorld123#"
amount: 		100
currency: 		"KZT"
terminal: 		"67e34d63-102f-4bd1-898e-370781d0074d"
postLink:       ""
failurePostLink: ""

Поле	Описание
grant_type	тип авторизации, для проведения платежа используется тип client_credentials
scope	ресурс
client_id	Идентификатор коммерсанта, можно получить в кабинете, выдается при регистрации
client_secret	Ключ доступа коммерсанта, можно получить в кабинете, выдается при регистрации
invoiceID	Номер заказа, генерируется коммерсантом, должен быть уникальный для каждого нового заказа,от 6 до 15 цифр. Если ваш номер заказа содержит более 6 цифр, то дополнительно уникальность должна соблюдаться по последним 6ти цифрам
secret_hash	дополнительное секретное значение(строка), сгенерированное системой интернет-магазина, которое будет возвращено на Postlink, ОБЯЗАТЕЛЬНОЕ ЗНАЧЕНИЕ
amount	Сумма заказа
currency	Валюта
terminal	Идентификатор точки продаж, можно получит в кабинете, выдается при регистрации
postLink	обязательный параметры, отправка postlink в случае успеха
failurePostLink	не обязательный параметры. отправка postlink в случае неудачи

Ответ

{
  "access_token":"DCEB8O_ZM5U7SO_T_U5EJQ",
  "expires_in": 7200,
  "refresh_token":"",
  "scope":" webapi usermanagement email_send verification statement statistics payment",
  "token_type":"Bearer"
}

Поле	Описание
access_token	Токен для проведения операции
expires_in	Время истечения токена
refresh_token	Не используется при данном типе авторизации
scope	Ресурс, для проведения платежа используется ресурс
token_type	Тип авторизации

Перенаправление на платежную страницу

На странице нужно подключить JS-библиотеку и вызвать в ней метод halyk.pay().

Прод версия

URL TEST: https://test-epay.epayment.kz/redesign-payform/payment-api.js
URL PROD: https://epay.homebank.kz/payform/payment-api.js

В метод halyk.pay() нужно передать следующие параметры.

var createPaymentObject = function(auth, invoiceId, amount) {
            var paymentObject = {
					invoiceId: "000000001",
             invoiceIdAlt:"8564546",
					backLink: "https://example.kz/success.html",
					failureBackLink: "https://example.kz/failure.html",
          autoBackLink: true,
					postLink: "https://example.kz/",
					failurePostLink: "https://example.kz/order/1123/fail",
					language: "rus",
					description: "Оплата в интернет магазине",
					accountId: "testuser1",
					terminal: "67e34d63-102f-4bd1-898e-370781d0074d",
          homebankCasKey: "66a5466d6e704ea2b9191b59b7f427dd"
					amount: 100,
              data: "{\"statement\":{\"name\":\"Arman Ali\",\"invoiceID\":\"80000016\"}}",
					currency: "KZT",
          phone: "77777777777",
          name:"Arman Ali",
          email: "example@example.com"
                };
          paymentObject.auth = auth;
          return paymentObject;
        };

halyk.pay(createPaymentObject(auth, invoiceId, amount));

Поле	Описание
invoiceId	Номер заказа, генерируется коммерсантом, должен быть уникальный для каждого нового заказа,от 6 до 15 цифр. Если ваш номер заказа содержит более 6 цифр, то дополнительно уникальность должна соблюдаться по последним 6ти цифрам
invoiceIdAlt	дополнительный номер заказа, генерируется коммерсантом, должен быть уникальный для каждого нового заказа,от 6 до 15 цифр
backLink	Ссылка для возврата в магазин при удачном платеже
failureBackLink	Ссылка для возврата в магазин при не удачном платеже
autoBackLink	Флаг автоматического перенаправления на URL из backLink
postLink	Уведомление о платеже
failurePostLink	Уведомление о неудачном платеже, если не заполнено, то информация будет отправлена на адрес указанный в postLink
language	Язык rus/kaz/eng
description	Описание заказа, допустимое количество символов 125 байтов
accountId	поле для указания идентификатора клиента магазина, обязателен при сохранений карты (cardSave:true) для сервиса получения списка сохраненных карт
terminal	Идентификатор магазина
homebankCasKey	кросс-авторизационный ключ полученый от системы Halyk Supper App
amount	Сумма заказа
currency	Валюта
phone	номер телефона клиента (не обязательно)
name	имя плательщика, только на латинице (не обязательно)
email	email клиента (не обязательно)
auth	Токен / передается полностью как объект, все данные полученные от epay по запросу токена
data	дополнительное поле транслируется в отчете при заполнении (не обязательно)

Postlink

На указанный URL указанный в поле postLink будет отправлено сообщение. В случае если вы не получили postlink, или для проверки запроса от системы ePay, необходимо воспользоваться сервисом Статус транзакции

Ответ в случае успеха:

{
    "accountId": "testuser1",
    "amount": 100,
    "approvalCode": "919412",
    "cardId": "",
    "cardMask": "440043...0128",
    "cardType": "HalykId",
    "code": "ok",
    "currency": "KZT",
    "dateTime": "2025-02-12T09:42:51.960781107+05:00",
    "description": "Оплата в интернет магазине",
    "email": "",
    "id": "a2bd2222-2as2-2d2r-f22d-22a33f453a2b",
    "invoiceId": "000000001",
    "invoiceIdAlt": "8564546",
    "ip": "92.211.91.91",
    "ipCity": "",
    "ipCountry": "",
    "ipDistrict": "",
    "ipLatitude": 0,
    "ipLongitude": 0,
    "ipRegion": "",
    "issuer": "HALYK BANK",
    "language": "RUS",
    "name": "ARMAN ALI",
    "phone": "",
    "reason": "success",
    "reasonCode": 0,
    "reference": "505555555554",
    "secure": "no",
    "secureDetails": "",
    "terminal": "67e34d63-102f-4bd1-898e-370781d0074d"
}

Поле	Описание
accountId	Идентификатор аккаунта пользователя, уникальный для каждого пользователя.
amount	Сумма транзакции в валюте, указанной в поле `currency` .
approvalCode	Код одобрения транзакции, генерируемый платежной системой.
cardId	Идентификатор карты.
cardMask	Маска номера карты, отображающая только последние четыре цифры (например, `440043...0128` ).
cardType	Тип транзакции, используемой для транзакции (например, `HalykId` ).
code	Код результата транзакции (например, `ok` для успешной транзакции).
currency	Валюта транзакции (например, `KZT` для казахстанских тенге).
dateTime	Дата и время выполнения транзакции в ISO 8601 формате.
description	Описание транзакции (например, `Оплата в интернет магазине` ).
email	Адрес электронной почты пользователя, если доступен; может быть пустым.
id	Уникальный идентификатор транзакции.
invoiceId	Номер заказа, генерируемый коммерсантом, должен быть уникальным для каждого нового заказа.
invoiceIdAlt	Дополнительный номер заказа, генерируемый коммерсантом.
ip	IP-адрес пользователя, совершившего транзакцию.
ipCity	Город пользователя, извлеченный из IP-адреса; может быть пустым.
ipCountry	Страна пользователя, извлеченная из IP-адреса; может быть пустым.
ipDistrict	Район пользователя, извлеченный из IP-адреса; может быть пустым.
ipLatitude	Широта местоположения пользователя, извлеченная из IP-адреса.
ipLongitude	Долгота местоположения пользователя, извлеченная из IP-адреса.
ipRegion	Регион пользователя, извлеченный из IP-адреса; может быть пустым.
issuer	Эмитент карты, использованной в транзакции (например, `HALYK BANK` ).
language	Язык, выбранный пользователем для транзакции (например, `RUS` для русского).
name	Имя пользователя, совершающего транзакцию (например, `ARMAN ALI` ).
phone	Номер телефона пользователя, если доступен; может быть пустым.
reason	Причина транзакции (например, `success` для успешной транзакции).
reasonCode	Код причины результата транзакции (например, `0` для успешной транзакции).
reference	Ссылка на транзакцию, используемая для дальнейшего отслеживания.
secure	Указывает, является ли транзакция безопасной (например, `no` для небезопасной).
secureDetails	Дополнительные детали безопасности транзакции, если доступны; может быть пустым.
terminal	Идентификатор терминала, через который была выполнена транзакция.

Коды ответов

Ответ в случае неудачи:

request: {
    "accountId": "testuser1",
    "amount": 100,
    "approvalCode": "",
    "cardId": "",
    "cardMask": "",
    "cardType": "",
    "code": "error",
    "currency": "KZT",
    "dateTime": "2025-02-12T09:42:51.960781107+05:00",
    "description": "Оплата в интернет магазин",
    "email": "",
    "id": "a2bd2222-2as2-2d2r-f22d-22a33f453a2b",
    "invoiceId": "000000001",
    "invoiceIdAlt": "8564546",
    "ip": "155.55.55.55",
    "ipCity": "Shymkent",
    "ipCountry": "Kazakhstan",
    "ipDistrict": "",
    "ipLatitude": 42.5555,
    "ipLongitude": 69.55,
    "ipRegion": "",
    "issuer": "HALYK BANK",
    "language": "RUS",
    "name": "",
    "phone": "77771231212",
    "reason": "Not sufficient funds",
    "reasonCode": 484,
    "reference": "507151111111",
    "secure": "no",
    "secureDetails": "",
    "terminal": "67e34d63-102f-4bd1-898e-370781d0074d"
}

markdown

Copy

Поле	Описание
accountId	Идентификатор аккаунта пользователя, уникальный для каждого пользователя.
amount	Сумма транзакции в валюте, указанной в поле `currency` .
approvalCode	Код одобрения транзакции; может быть пустым, если транзакция не была одобрена.
cardId	Идентификатор карты, если доступен; может быть пустым.
cardMask	Маска номера карты; может быть пустой, если информация недоступна.
cardType	Тип карты, используемой для транзакции; может быть пустым.
code	Код результата транзакции (например, `error` для ошибки).
currency	Валюта транзакции (например, `KZT` для казахстанских тенге).
dateTime	Дата и время выполнения транзакции в ISO 8601 формате.
description	Описание транзакции (например, `Оплата в интернет магазине` ).
email	Адрес электронной почты пользователя, если доступен; может быть пустым.
id	Уникальный идентификатор транзакции.
invoiceId	Номер заказа, генерируемый коммерсантом, должен быть уникальным для каждого нового заказа.
invoiceIdAlt	Дополнительный номер заказа, генерируемый коммерсантом.
ip	IP-адрес пользователя, совершившего транзакцию.
ipCity	Город пользователя, извлеченный из IP-адреса (например, `Shymkent` ).
ipCountry	Страна пользователя, извлеченная из IP-адреса (например, `Kazakhstan` ).
ipDistrict	Район пользователя, извлеченный из IP-адреса; может быть пустым.
ipLatitude	Широта местоположения пользователя, извлеченная из IP-адреса (например, `42.5555` ).
ipLongitude	Долгота местоположения пользователя, извлеченная из IP-адреса (например, `69.55` ).
ipRegion	Регион пользователя, извлеченный из IP-адреса; может быть пустым.
issuer	Эмитент карты, использованной в транзакции (например, `HALYK BANK` ).
language	Язык, выбранный пользователем для транзакции (например, `RUS` для русского).
name	Имя пользователя, совершающего транзакцию; может быть пустым.
phone	Номер телефона пользователя (например, `77771231212` ).
reason	Причина отказа в транзакции (например, `Not sufficient funds` ).
reasonCode	Код причины результата транзакции (например, `484` для недостатка средств).
reference	Ссылка на транзакцию, используемая для дальнейшего отслеживания.
secure	Указывает, является ли транзакция безопасной (например, `no` для небезопасной).
secureDetails	Дополнительные детали безопасности транзакции, если доступны; может быть пустым.
terminal	Идентификатор терминала, через который была выполнена транзакция.