invoice link API

Link to API payment

Documentation for the API for creating invoices in the ePay electronic payment system:

**Getting a token:**

**Method: 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"
secret_hash: "JDKCNDDGGDTPSKJD"


**Response**

```json
{
    "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: Method: POST

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

Data for testing:

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

Input parameters: Метод: 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"
}

Field	Description
shop_id (string)	Store ID, issued by the system when registering the store, required
account_id (string)	The account number of the store in the epay system, generated by the merchant, mandatory
invoice_id (string)	Unique identifier of the number in the store's system, generated by the merchant, optional
amount (number)	The amount of the invoice, required
language (string)	The language in which the account information should be presented (acceptable values: "rus", "kaz", "eng"), required
description (string)	Account description, 125 characters allowed, required
expire_period (string)	Account validity period. Format: "[number][time unit]", where the time unit can take the value "d" (days). For example, the "2d" invoice is valid for two days, mandatory
recipient_contact (string)	Email address of the account recipient, required
recipient_contact_sms (string)	Mobile phone number of the account recipient in the format "+7XXXXXXXXXX", required
notifier_contact_sms (line, optional)	Mobile phone number for sending payment notifications in the format "+7XXXXXXXXXX"
currency (line)	Account currency (acceptable values: "KZT"), required
post_link (string, optional)	The URL to which the POST request will be sent after successful payment of the invoice
failure_post_link (string, optional)	The URL to which the POST request will be sent in case of unsuccessful payment of the invoice

Answer:

{
    "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"
}

Field	Description
id (string)	Unique identifier of the account in the ePay system
shop_id (string)	The identifier of the store registered in the ePay system
amount (number)	Invoice amount
invoice_id (string)	Unique identifier of the invoice in the store's system, from 6 to 15 digits
language (string)	The language in which the information about the invoice is presented
currency (string)	Account currency
description (line)	Account description
account_id (line)	Store account ID
recipient_contact (line)	Email address of the account recipient
recipient_contact_sms (line)	Mobile phone number
expiry_period (string)	Account validity period
terminal_id (GUID)	The number of the virtual terminal in the ePay system

Checking the link status The service allows you to check the status of the generated link

Authorization required Method: 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 IRPNGDU-PBYMXBCXTC5AMG

URL:

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

Method: POST

Request

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

Two parameters must be passed to the "paging" block:

"skip" - the number of records to be skipped;
"limit" - the number of records to be displayed on the page.

In the "searchParameters" block, three parameters must be passed, you can also search through a variety of fields (the query example shows how):

"name" is the name of the field (filter) that will be searched in the database, in our case by the order number invoice_id;
"method" - the search method (specify in the following form : between, like , =);
"searchParameter" - search parameters.When using the between search method, 2 parameters must be passed, when using like, pass one parameter that contains the % sign, with the in search method, at least 1 parameter must be used. If the parameters are not passed correctly, an error will be returned. The order number must be specified in the request. This search parameter is required.

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
        }
    ]
}

Deactivation of the payment link

The service allows you to deactivate the link so that the client cannot pay using it (at the same time, if a successful payment was made using the link, it will not be possible to re-use it, on our side there is a restriction on the combination of terminal number + invoice) That is, if a successful payment was made via the link, there is no need to deactivate it. Deactivating the link does not affect an already completed payment in any way.

Authorization is required.

Getting a token Method: 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

Method: PUT_

Invoicelinkid is the unique identifier of the account in the ePay system when responding to the generated link