Saving a payment card

Upon registration, you will be given the data that you will need to use when making the payment:


TerminalID	Store ID
ClientID	Client ID
ClientSecret	Secret key

Test merchant


url	https://test-epay.homebank.kz
email	epay@halykbank.kz
password	XZG1E@Mm
ClientID	test
ClientSecret	yF587AV9Ms94qN2QShFzVR3vFnWkhjbAK3sG
TerminalID	67e34d63-102f-4bd1-898e-370781d0074d

Test payment card

PAN	Expire Date	CVC	Status
4405639704015096	01/27	321	unlock
5522042705066736	01/27	775	unlock
377514500004820	01/28	0198	unlock
4003032704547597	09/20	170	lock
5578342710750560	09/20	254	lock

Getting a token to make a payment (for each operation, you must receive and use the original token)

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: "webapi usermanagement email_send verification statement statistics payment"
client_id: "test"
client_secret: "yF587AV9Ms94qN2QShFzVR3vFnWkhjbAK3sG"
invoiceID: "000000001"
amount: 0
currency: "USD"
terminal: "67e34d63-102f-4bd1-898e-370781d0074d"
postLink: ""
failurePostLink: ""

Field	Description
grant_type	Authorization type, the client_credentials type is used for making a payment
scope	Resource
client_id	Merchant's ID, which can be obtained in the cabinet, is issued upon registration
client_secret	The merchant's access key, which can be obtained in the cabinet, is issued upon registration
invoiceID	The order number generated by the merchant must be unique for each new order, from 6 to 15 digits. If your order number contains more than 6 characters, then additionally uniqueness must be observed for the last 6 characters
amount	Order amount
currency	Currency
terminal	The ID of the point of sale, which can be obtained in the cabinet, is issued during registration
postLink	Required parameters, sending a postlink if successful
failurePostLink	Optional parameters, sending a postlink in case of failure

Response

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

Field	Description
access_token	The token for the operation
expires_in	Token Expiration Time
refresh_token	It is not used for this type of authorization
scope	Resource, the payment resource is used to make the payment
token_type	Authorization type

Making a payment

On the page, you need to connect the JS-library and call the halyk.cardverification() method in it.

Production version

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

The following parameters must be passed to the halyk.cardverification() method.

   var createPaymentObject = function(auth, invoiceId, amount) {
       var paymentObject = {
           InvoiceID: "000000001",
backLink: "https://example.kz/success.html ",
failureBackLink: "https://example.kz/failure.html ",
postLink: "https://example.kz /",
language: "rus",
description: "Card registration",
AccountId: "testuser1",
terminal: "67e34d63-102f-4bd1-898e-370781d0074d",
amount: 0,
currency: "USD",
cardSave: true,
PaymentType: "cardVerification"
};
       paymentObject.auth = auth;
       return paymentObject;
   };

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

Field	Description
invoiceID	The order number generated by the merchant must be unique for each new order, from 6 to 15 digits. If your order number contains more than 6 digits, then additionally uniqueness must be observed for the last 6 digits
backLink	Link to return to the store upon successful payment
failureBackLink	Link to return to the store in case of a failed payment
postLink	Payment Notification
language	Language rus/kaz/eng
description	Order description, the allowed number of characters is 125 bytes
AccountId	Field for specifying the store's customer ID, required field when saving the card (cardSave: true)
terminal	The store ID, which can be obtained in the cabinet, is issued upon registration
amount	The amount to save the card is always 0
currency	Currency, always USD to save the card
cardSave	Required parameter for saving the map, passed as boolean
paymentType	Operation type - card verification
ip	the IP address where the request was made from
ipCountry	Сountry name
ipCity	Name of the city
ipRegion	Name of the region
ipDistrict	Name of the district
ipLatitude	Latitude
ipLongitude	Longitude

Post link

A message will be sent to the specified URL specified in the postLink field. If you have not received a postlink, we recommend using the [Transaction Status service] (https://epayment.kz/docs/check-status-payment)

Response in an event of success:

{
"acountId":"9398101000014416472",
"amount":800,
"approvalCode":"178644",
"cardId":"2cd0fb54-9855-14a6-e063-1b01010a84c4",
"cardMask":"440043...0128",
"cardType":"VISA",
"code":"ok",
"currency":"KZT",
"dateTime":"2025-02-12T09:42:51.960781107+05:00",
"description":"ONAY!",
"email":"",
"id":"a1bd0589-3ac9-4a2e-a31d-67a33f453a2b",
"invoiceId":"33456850",
"ip":"91.215.96.94",
"ipCity":"",
"ipCountry":"",
"ipDistrict":"",
"ipLatitude":0,
"ipLongitude":0,
"ipRegion":"",
"issuer":"JSC KASPI BANK",
"language":"RUS",
"name":"",
"phone":"77775903128",
"reason":"success",
"reasonCode":0,
"reference":"504355533594",
"secret_hash":"ZitLN1VLd21hUnFOSTJKbmg0UVdYVm8z",
"secure":"yes",
"secureDetails":"F",
"terminal":"9d40257c-bdfc-4c5e-9c3c-0c2a16bfc5a4"
}

Error codes

Response in case of failure:

{
"accountId":"9398101000006384023",
"amount":200,
"approvalCode":"",
"cardId":"",
"cardMask":"",
"cardType":"",
"code":"error",
"currency":"KZT",
"dateTime":"2025-02-12T09:42:53.036675+05:00",
"description":"ONAY!",
"email":"",
"id":"03c6de6e-0028-42fa-9199-561d78e59789",
"invoiceId":"33456910",
"ip":"95.82.119.153",
"ipCity":"Almaty",
"ipCountry":"Kazakhstan",
"ipDistrict":"",
"ipLatitude":43.2638,
"ipLongitude":76.9293,
"ipRegion":"",
"issuer":"JSC KASPI BANK",
"language":"RUS",
"name":"",
"phone":"77476080308",
"reason":"Authentication failed",
"reasonCode":473,
"reference":"",
"secret_hash":"T1hDaWhlay9NUysxRTA2djFFZnpTVDNU",
"secure":"no",
"secureDetails":"",
"terminal":"9d40257c-bdfc-4c5e-9c3c-0c2a16bfc5a4"
}