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:

TerminalIDStore identification
ClientIDClient Identification
ClientSecretSecret Key

Test merchant

urlhttps://test-epay.homebank.kz
emailepay@halykbank.kz
passwordXZG1E@Mm
ClientIDtest
ClientSecretyF587AV9Ms94qN2QShFzVR3vFnWkhjbAK3sG
TerminalID67e34d63-102f-4bd1-898e-370781d0074d

Test payment card

PANExpire DateCVCStatus
440563970401509601/25815unlock
552204270506673601/25525unlock
37751450000482001/254169lock
400303270454759709/20170lock
557834271075056009/20254lock

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"

FieldDescription
grant_typeAuthorization type, client_credentials used to process payment
scopeResource
client_idMerchand Identification. Can be retrieved on the merchant account page, initially received when registering
client_secretMerchant access key. Can be retrieved on the merchant account page, initially received when registering
invoiceIDOrder number. Generated by the merchant. Must be unique for every new order
secret_hashadditional secret value(string) generated by the online store system which will be returned to Postlink
amountOrder amount
curencyTransaction currency
terminalSalespoint 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"
}

FieldDescription
access_tokenA token that is used for payment processing.
expires_inExpiry period of a token
refresh_tokenNot used with this type of authorization
scopeResource, payment type used for payment authorization
token_typeAuthorization 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\"}}",
          cardSave: true  //Параметр должен передаваться как Boolean
                };
          paymentObject.auth = auth;
          return paymentObject;
        };

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

FieldDescription
invoiceIdThe 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
invoiceIdAltAn alternative order number, generated by the merchant, must be unique for each new order, from 6 to 15 digits
backLinkLink to get back to the store when payment succeeds.
failureBackLinkLink to get back to the store when payment fails.
postLinkNotification about the payment success.
failurePostLinkNotification about the payment failure. If not given, information would be sent back to the address that is specified in postLink.
languageLanguage rus/kaz/eng
descriptionOrder description
accountIdOption field fir client identification number
terminalStore identification
amountOrder amount
currencyOrder currency
authToken / is transmitted completely as an object, all data received from epay upon request of the token
callBkSend back the object { success: true | false }
dataSend 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
}