Payment widget

Important: When studying this document, please take into account that using the Apple Pay payment method is not possible, since the payment tokenization policy does not allow the Apple Pay button to be displayed on the page that is opened using the widget.

When registered, you will be given data, that is needed when making the payment:


TerminalID	Store identification
ClientID	Client Identification
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/25	815	unlock
5522042705066736	01/25	525	unlock
377514500004820	01/25	4169	lock
4003032704547597	09/20	170	lock
5578342710750560	09/20	254	lock

Receiving a token for payment processing (for each operation it is necessary to obtain 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: "ClientID"
client_secret: "ClientSecret"
invoiceID: "Order number"
secret_hash: "JDKCNDDGGDTPSKJD"
amount: 100
curency: "KZT"
terminal: "TerminalID"

Field	Description
grant_type	Authorization type, client_credentials used to process payment
scope	Resource
client_id	Merchand Identification. Can be retrieved on the merchant account page, initially received when registering
client_secret	Merchant access key. Can be retrieved on the merchant account page, initially received when registering
invoiceID	Order number. Generated by the 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
curency	Transaction currency
terminal	Salespoint identification. Can be retrieved on the merchant account page, initially generated when registered.

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	A token that is used for payment processing.
expires_in	Expiry period of a token
refresh_token	Not used with this type of authorization
scope	Resource, payment type used for payment authorization
token_type	Authorization type

Calling Widge

You need to connect a JS-Library on a page and make a call to halyk.showPaymentWidget().

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

You must pass these parameters when calling halyk.showPaymentWidget(createPaymentObject(auth, invoiceId, amount), callBk)

var createPaymentObject = function(auth, invoiceId, amount) {
          var paymentObject = {
					invoiceId: "Номер заказа",
          invoiceIdAlt: "000001",
					backLink: "https://example.kz/success.html",
					failureBackLink: "https://example.kz/failure.html",
					postLink: "https://example.kz/",
					failurePostLink: "https://example.kz/order/1123/fail",
					language: "RUS",
					description: "Оплата в интернет магазине",
					accountId: "testuser1",
					terminal: "TerminalID",
					amount: 100,
          name: "Arman Ali",
					currency: "KZT",
          data: "{\"statement\":{\"name\":\"Arman     Ali\",\"invoiceID\":\"80000016\"}}",
                };
          paymentObject.auth = auth;
          return paymentObject;
        };

halyk.showPaymentWidget(createPaymentObject(auth, invoiceId, amount), callBk);

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 characters, then additional uniqueness must be maintained in the last 6 characters

invoiceIdAlt	An alternative order number, generated by the merchant, must be unique for each new order, from 6 to 15 digits

backLink	Link to get back to the store when payment succeeds.
failureBackLink	Link to get back to the store when payment fails.
postLink	Notification about the payment success.
failurePostLink	Notification about the payment failure. If not given, information would be sent back to the address that is specified in postLink.
language	Language rus/kaz/eng
description	Order description
accountId	Option field fir client identification number
terminal	Store identification
amount	Order amount
currency	Order currency
auth	Token / is transmitted completely as an object, all data received from epay upon request of the token
callBk	Send back the object { success: true \| false }
data	Send back the object { success: true \| false }

halyk.showPaymentWidget()

takes a callback as a second argument. The callback is called depending on the result of payment processing.

Post link

The message would be sent to the URL that is specified in postLink field

In case of success:

{
  "id": "ffffffff-0000-000f-f000-00f0000f000f",
  "dateTime": "2020-01-01T00:00:00.00000+06:00",
  "invoiceId": "10000000001",
  "invoiceIdAlt":"8564546",
  "amount": 100,
  "currency": "KZT",
  "terminal": "67e34d63-102f-4bd1-898e-370781d0074d",
  "accountId": "1",
  "description": "Оплата в интернет магазине",
  "language": "RU",
  "cardMask": "4444...4444",
  "cardType": "",
  "issuer": "Halyk bank",
  "reference": "109600746891"
  "approvalСode": "730190",
  "code": 0,
  "secure": "Yes",
  "tokenRecipient": "",
  "code": "ok",
  "reason": "",
  "reasonCode": 0,
  "name": "CARD HOLDER",
  "email": "ch@example.kz",
  "phone": "77777777777",
  "ip": "5.188.155.135",
  "ipCountry": "Kazakhstan",
  "ipCity": "Almaty",
  "ipRegion": "",
  "ipDistrict": "",
  "ipLongitude": 76.9293,
  "ipLatitude": 43.2638,
  "cardId": "e7e2587f-de26-4f41-ae1f-80c1fea31728"
}

In case of failure:

{
   "id": "ffffffff-0000-000f-f000-00f0000f000f",
   "dateTime": "2020-01-01T00:00:00.00000+06:00",
   "invoiceId": "10000000001",
   "invoiceIdAlt":"8564546",
   "amount": 100,
   "currency": "KZT",
   "terminal": "67e34d63-102f-4bd1-898e-370781d0074d",
   "accountId": "1",
   "description": "Оплата в интернет магазине",
   "language": "RU",
   "cardMask": "4444...4444",
   "cardType": "",
   "issuer": "Halyk bank",
   "reference": "",
   "secure": "yes",
   "tokenRecipient": "",
   "code": "error",
   "reason": "описание ошибки",
   "reasonCode": -498,
   "name": "CARD HOLDER",
   "email": "ch@example.kz",
   "phone": "77777777777",
   "ip": "5.188.155.135",
   "ipCountry": "Kazakhstan",
   "ipCity": "Almaty",
   "ipRegion": "",
   "ipDistrict": "",
   "ipLongitude": 76.9293,
   "ipLatitude": 43.2638
}