Payment page by HalykID

Before starting work, you need to contact halykid@halykbank.kz to obtain test data and implement the process of acquiring the homebankCasKey authorization token. This token will be used for further data transfer to the ePay system.

When registred, you will be given credentials that you would need for making payments:


TerminalID	Store Identification
ClientID	Client Identificator
ClientSecret	Secret Keys

Receiving a token for payment processing

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

Request

Body: form-data

grant_type: 	"client_credentials"
scope: 			"payment"
client_id: 		"test"
client_secret: 	"yF587AV9Ms94qN2QShFzVR3vFnWkhjbAK3sG"
invoiceID: 		"000000001"
secret_hash: "JDKCNDDGGDTPSKJD"
amount: 		100
currency: 		"KZT"
terminal: 		"67e34d63-102f-4bd1-898e-370781d0074d"
postLink:       ""
failurePostLink: ""

Поле	Описание
grant_type	authorization type. client_credentials are used for payment processing
scope	resource
client_id	Merchant id (can be obtained on the account page, first given when registered)
client_secret	Merchant's access key (can be obtained on the account page, first given when registered)
invoiceID	Order number (generated by merchant, must be unique for every new order)
secret_hash	additional secret value(string) generated by the online store system which will be returned to Postlink
amount	Order Amount
currency	Currency
terminal	Sale point's id (can be obtained on the account page, first given when registered)
postLink	Optional parameter. Sends postlink in case of success.
failurePostLink	Optional parameter. Sends postlink in case of failure.

Response

{
  "access_token":"DCEB8O_ZM5U7SO_T_U5EJQ",
  "expires_in": 7200,
  "refresh_token":"",
  "scope":"payment",
  "token_type":"Bearer"
}

Field	Description
access_token	Token for payment processing
expires_in	Expiry time
refresh_token	Not used in current type of request
scope	Resource. In order to process a payment "payment" resouce is used. Ресурс, для проведения платежа используется ресурс payment
token_type	Type of the token

Redirection on payment page

You must connect JS-library to the page and call a halyk.pay() method.

Production version

URL: https://test-epay.homebank.kz/payform/payment-api.js

You must specify these paramteres in halyk.pay() method

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

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

Field	Description
invoiceId	Order number. Generated by a merchant, must be unique for every new order
invoiceIdAlt	Additional order number, assigned by the merchant, must be unique for each new order, from 6 to 15 digits.
backLink	A link to get back on a shop page when payment is successful
failureBackLink	A link to get back on a shop page when payment failed
postLink	Notification of a payment
failurePostLink	A notification of an unsuccessfull payment. Information will be sent to the address in postLink if no information is present
language	Language
description	Order description
accountId	Optional field. Used when a merchant has a unique id assigned to the client
terminal	Id of a sale point
amount	Order amount
currency	Transaction currency
phone	Client's phone number optional
email	Client's email address optional
auth	Authorization tokenn
data	additional field is transmitted in the report when filled in (optional)

Post link

URL in postLink will be used to send a message.

Response in an event of success:

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

Error codes

Response in an event of a failure:

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