API төлеміне сілтеме

ЕPay электрондық төлемдер жүйесінде шоттарды құру API-интерфейсіне арналған құжаттама:

Токенді алу:

Әдісі: 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"}
}

URL:

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 (толтыруға міндетті емес жол)Шотты сәтті төлегеннен кейін POST-сұрау салуға жіберілетін URL-мекенжайы
failure_post_link (толтыруға міндетті емес жол)Шотты төлеу сәтсіз болған жағдайда POST-сұрау салуға жіберілетін URL-мекенжайы

Жауап:

{
    "id": "19c435ae-fbe6-4761-863f-381f6a0fe824",
    "shop_id": "4e16cfde-f3e9-49c6-8cf9-2d3f080f739c",
    "amount": 100,
    "invoice_id": "25458124232312321",
    "language": "rus",
    "currency": "KZT",
    "description": "asdasdasdas",
    "account_id": "0003413423",
    "recipient_contact": "EXAMPLE@halykbank.kz",
    "recipient_contact_sms": "+777711111111",
    "notifier_contact": "",
    "notifier_contact_sms": "+777711111111",
    "expire_period": "2d",
    "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 (жол)Ерay жүйесінде тіркелген дүкен сәйкестендіргіші
amount (сан)Шот сомасы
invoice_id (жол)Дүкен жүйесіндегі шоттың бірегей сәйкестендіргіші, 6-дан 15 цифрға дейін
language (жол)Шот туралы ақпарат берілген тіл
currency (жол)Шот валютасы
description (жол)Шоттың сипаттамасы
account_id (жол)Дүкен шотының сәйкестендіргіші
recipient_contact (жол)Шот алушының электрондық мекенжайы
recipient_contact_sms (жол)Ұялы телефон нөмірі
expire_period (жол)Шоттың қолданылу кезеңі
terminal_id (GUID)ePay жүйесіндегі виртуалды терминал нөмірі

Сілтеме күйін тексеру Қызмет жасалған сілтеменің күйін тексеруге мүмкіндік береді

Авторизация қажет Әдіс: 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"

Жауап

{
    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:

TEST URL POST https://testepay.homebank.kz/api/invoice-links
PROD URL POST https://epay-api.homebank.kz/invoice-links

Әдіс: 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;
  • "әдіс" - іздеу әдісі (келесі түрде көрсетіңіз: 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"

Жауап

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

Aвторизация: Bearer DCEB8O_ZM5U7SO_T_U5EJQ

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

Әдіс: PUT

Invoicelinkid-жасалған сілтемеге жауап беру кезінде ePay жүйесіндегі бірегей шот идентификаторы