Документация для API-интерфейса создания счетов в системе электронных платежей ePay:

Тестовые авторизационные данные:

**CLIENT_ID**|-"halykfinanceUSD"|
**CLIENT_SECRET**|-"U01gQZVL##lJ$NhJ"|
**TERMINAL_ID**|-"d9d7978c-d6ee-4ec0-8cda-165251a4bf16"|
**SHOP_ID**|-"04f25a4b-d2bd-4dd8-b3a7-9390be4774c4"|
**EMAIL**|-"halykfinanceUSD@halykbank.nb"|
**PASSWORD**|-"XVp36qar"|

Получения токена:

Метод: POST

TEST URL POST https://testoauth.homebank.kz/epay2/oauth2/token
PROD URL POST https://epay-oauth.homebank.kz/oauth2/token

Request OAuth 2.0

Body: form-data

    grant_type:        "password"
    username:          "halykfinanceUSD@halykbank.nb"
    password:          "XVp36qar"
    scope:             "api"
    client_id:         "halykfinanceUSD"
    client_secret:     "U01gQZVL##lJ$NhJ"

Response

  {
    "access_token": "IRPNGDU-PBYMXBCXTC5AMG",
    "expires_in": "900",
    "refresh_token": "O8EGZOGOVVAQGUAADC_WBG",
    "scope": "webapi usermanagement email_send verification statement statistics payment",
    "token_type": "Bearer"}

Authorization: Bearer DCEB8O_ZM5U7SO_T_U5EJQ

URL: Метод: POST

URL prod https://epay-api.homebank.kz/invoice
URL test https://testepay.homebank.kz/api/invoice

данные для тестирования:

shop_id prod: e16cfde-f3e9-49c6-8cf9-2d3f080f739c
shop_id test: 04f25a4b-d2bd-4dd8-b3a7-9390be4774c4

Входные параметры: Метод: JSON


{
    "shop_id": "04f25a4b-d2bd-4dd8-b3a7-9390be4774c4",
    "account_id": "0003413423",
    "invoice_id": "25458124232312321",
    "amount": 100,
    "language": "rus",
    "description": "asdasdasdas",
    "expire_period": "1d",
    "recipient_contact": "EXAMPLE@halykbank.kz",
    "recipient_contact_sms": "+777711111111",
    "notifier_contact_sms": "",
    "currency": "KZT",
    "post_link": "https//mail.ru",
    "failure_post_link": "https//mail.ru",
    "back_link":"https//mail.ru",
    "failure_back_link":"https//mail.ru"
}
ПолеОписание
shop_id (строка)- ID магазина, выдается системой при регистрации магазина, обязательное
account_id (строка)- номер счета магазина в системе epay, генериурется коммерсантом, обязательное
invoice_id (строка)- уникальный идентификатор номера в системе магазина, генериурется коммерсантом, обазательное
amount (число)- сумма счета, обязательное
language (строка)- язык, на котором должна быть представлена информация о счете (допустимые значения: "rus", "kaz", "eng"), обязательное
description (строка)- описание счета, допустимое количество символов 125, обязательное
expire_period (строка)- период действия счета. Формат: "[число][единица времени]", где единица времени может принимать значение "d" (дни). Например, "2d" - счет действителен в течение двух дней, обязательное
recipient_contact (строка)- электронный адрес получателя счета, обязательное
recipient_contact_sms (строка)- номер мобильного телефона получателя счета в формате "+7XXXXXXXXXX", обязательное
notifier_contact_sms (строка, необязательный к заполнению)- номер мобильного телефона для отправки уведомлений об оплате в формате "+7XXXXXXXXXX".
currency (строка)- валюта счета (допустимые значения: "KZT"), обязательное
post_link (строка, необязательный)- URL-адрес, на который будет отправлен POST-запрос после успешной оплаты счета.
failure_post_link (строка, необязательный)- URL-адрес, на который будет отправлен POST-запрос в случае неуспешной оплаты счета.
back_link- Ссылка для возврата в магазин при удачном платеже.
failure_post_link- Ссылка для возврата в магазин при неудачном платеже.

Ответ:

{
    "id": "19c435ae-fbe6-4761-863f-381f6a0fe824",
    "shop_id": "4e16cfde-f3e9-49c6-8cf9-2d3f080f739c",
    "amount": 100,
    "invoice_id": "25458124232312321",
    "language": "rus",
    "currency": "KZT",
    "description": "test",
    "account_id": "0003413423",
    "recipient_contact": "EXAMPLE@halykbank.kz",
    "recipient_contact_sms": "+777711111111",
    "notifier_contact": "",
    "notifier_contact_sms": "+777711111111",
    "expire_period": "1d",
    "post_link": "",
    "failure_post_link": "",
    "created_date": "2023-03-28T10:04:10.997074088+06:00",
    "expire_date": "2023-03-30T10:04:10.997074088+06:00",
    "status": "ACTIVE",
    "updated_date": "0001-01-01T00:00:00Z",
    "invoice_url": " https://testepay.homebank.kz/api/redirect/invoice-link/19c435ae-fbe6-4761-863f-381f6a0fe824",
    "merchant_id": " ad638b1d-e515-4b9c-aab3-d3500735f6eb",
    "terminal_id": "d9d7978c-d6ee-4ec0-8cda-165251a4bf16"
}
ПолеОписание
id (строка)- уникальный идентификатор счета в системе ePay.
shop_id (строка)- идентификатор магазина, зарегистрированного в системе ePay.
amount (число)- сумма счета.
invoice_id (строка)- уникальный идентификатор счета в системе магазина, от 6 до 15 цифр.
language (строка)- язык, на котором представлена информация о счете.
currency (строка)- валюта счета.
description (строка)- описание счета.
account_id (строка)- идентификатор счета магазина.
recipient_contact (строка)- электронный адрес получателя счета.
recipient_contact_sms (строка)- номер мобильного телефона
expire_period (строка)- период действия счета
post_link (строка)- URL-адрес, на который будет отправлен POST-запрос после успешной оплаты счета.
failure_post_link (строка)- URL-адрес, на который будет отправлен POST-запрос после успешной оплаты счета.
created_date- Дата создания ссылки
_expire_date- Срок действия ссылки
status- статус ссылки на оплату.
invoice_url- ссылка на оплату
terminal_id (GUID)- номер виртуального терминала в системе ePay

Проверка статуса ссылки Сервис позволяет проверить статус сгенерированной ссылки

Требуется авторизация Метод: POST Метод: POST

TEST URL POST https://testoauth.homebank.kz/epay2/oauth2/token
PROD URL POST https://epay-oauth.homebank.kz/oauth2/token

Request OAuth 2.0

Body: form-data

    grant_type:        "password"
    username:          "halykfinanceUSD@halykbank.nb"
    password:          "XVp36qar"
    scope:             "api"
    client_id:         "halykfinanceUSD"
    client_secret:     "U01gQZVL##lJ$NhJ"

Responce

{
    access_token": "IRPNGDU-PBYMXBCXTC5AMG",
    "expires_in": "900",
    "refresh_token": "O8EGZOGOVVAQGUAADC_WBG",
    "scope": "webapi usermanagement email_send verification statement statistics payment",
    "token_type": "Bearer"}

}

Authorization: Bearer DCEB8O_ZM5U7SO_T_U5EJQ

URL: Метод: POST

Request

{
    "paging": {
        "skip": 0,
        "limit": 20
    },
    "searchParameters": [
        {
            "name": "invoice_id",
            "method": "=",
            "searchParameter": [
                "200220241201"
            ]
        }
    ],
    "orderParameters": {
        "field": "id",
        "typeOrder": "DESC"
    }
}

В блок "paging" , необходимо передавать два параметра: "skip" - количество записей которые необходимо пропустить; "limit" - количество записей которые необходимо вывести на странице. В блок "searchParameters", необходимо передавать три параметра, так же можно производить поиск по множеству полей (в примере запроса показано как) "name" - наименование поля(фильтра) по которому будет происходить поиск в БД, в нашем случае по номеру заказа invoice_id; "method" - метод поиска (указывать в следующем виде : between, like , =) ; "searchParameter" - параметры поиска.При использование метода поиска between необходимо передавать 2 параметра, при использование like, передавать один параметр который содержит знак %, при методе поиска in необходимо использовать минимум 1 параметр. В случае не корректно переданных параметров , будет возвращаться ошибка. В запросе необходимо указывать номер заказа. Данный параметр поиска является обязательным.

Response

{
    "TotalCount": 1,
    "Records": [
  {
            "id": "39400628-6ebd-4640-9a25-116fb847db37",
            "shop_id": "04f25a4b-d2bd-4dd8-b3a7-9390be4774c4",
            "amount": 400,
            "invoice_id": "200220241201",
            "language": "rus",
            "currency": "KZT",
            "description": "tes ",
            "account_id": "",
            "recipient_contact": "test@test.kz",
            "recipient_contact_sms": "+77778877887",
            "notifier_contact": "",
            "notifier_contact_sms": "+77778877887",
            "expire_period": "2d",
            "post_link": "https://epay.homebank.kz/payform",
            "failure_post_link": "https://testmerchant/order/1123/fail",
            "back_link": "",
            "failure_back_link": "",
            "created_date": "2024-02-20T15:15:29.289897+06:00",
            "expire_date": "2024-02-22T15:15:29.289897+06:00",
            "status": "CHARGED",
            "updated_date": "0001-01-01T05:07:48+05:07",
            "invoice_url": "https://testepay.homebank.kz/api/redirect/invoice-link/39400628-6ebd-4640-9a25-116fb847db37",
            "merchant_id": "ad638b1d-e515-4b9c-aab3-d3500735f6eb",
            "terminal_id": "d9d7978c-d6ee-4ec0-8cda-165251a4bf16",
            "card_save": false
        }
    ]
}

Деактивация ссылки на оплату

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

Требуется авторизация

Получение токена Метод: POST

TEST URL POST https://testoauth.homebank.kz/epay2/oauth2/token
PROD URL POST https://epay-oauth.homebank.kz/oauth2/token

Request OAuth 2.0

Body: form-data

    grant_type:        "password"
    username:          "halykfinanceUSD@halykbank.nb"
    password:          "XVp36qar"
    scope:             "webapi usermanagement email_send verification statement statistics payment"
    client_id:         "halykfinanceUSD"
    client_secret:     "U01gQZVL##lJ$NhJ"

Response

{
  "access_token": "IRPNGDU-PBYMXBCXTC5AMG",
    "expires_in": "900",
    "refresh_token": "O8EGZOGOVVAQGUAADC_WBG",
    "scope": "webapi usermanagement email_send verification statement statistics payment",
    "token_type": "Bearer"}

Authorization: Bearer DCEB8O_ZM5U7SO_T_U5EJQ

URL : https://testepay.homebank.kz/api/deactivate/invoice-links/:invoicelinkid

Метод: PUT

Invoicelinkid – уникальный идентификатор счета в системе ePay при ответе сгенерированной ссылки