API based payments

To work through the company's API, PCI DSS certification is required.

Upon registration, you will be provided with data that will need to be used when making a payment:

TerminalID - store identifier
ClientID - client identifier
ClientSecret - secret key

Data for test payments:


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 (an original token must be obtained and used for each operation)

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

Request

grant_type: "client_credentials"
scope: "webapi usermanagement email_send verification statement statistics payment"
client_id: "ClientID"
client_secret: "ClientSecret"
invoiceID: "Номер заказа"
secret_hash: "JDKCNDDGGDTPSKJD"
amount: 100
currency: "KZT"
terminal: "67e34d63-102f-4bd1-898e-370781d0074d"

Response

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

Input parameters

Field	Description	Required/Optional
amount	Payment amount	Required
currency	Currency	Required
name	Cardholder name	Required
сryptogram	Encrypted payment card parameters	Required
invoiceId	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, uniqueness must also be maintained for the last 6 characters	Required
description	This field contains information about the goods or services for which the payment is being made	Required
accountId	Customer identifier in the merchant system or another additional parameter at the discretion of the merchant	Optional
email	Customer email	Optional
phone	Customer phone	Optional
postLink	Link for sending the authorization result to the store	Required
failurePostLink	Link to send unsuccessful authorization results or error information to the store.	Optional
cardsave	Card saving parameter, true - save the card, false - do not save, boolean type	Required
data	Additional field transmitted in the report when filling out	Optional

Preparing a cryptogram

Cryptogram structure:

{
  hpan string
  expDate string
  cvc string
  terminalId string
}

Exаmple:

{
 "hpan":"4003032704547597","
 expDate":"1022",
 "cvc":"636",
 "terminalId":"67e34d63-102f-4bd1-898e-370781d0074d"
}

The structure must be encrypted using the public RSA key, which is available at https://epay-api.homebank.kz/public.rsa https://testepay.homebank.kz/api/public.rsa

PROD URL https://epay-api.homebank.kz/public.rsa
TEST URL https://testepay.homebank.kz/api/public.rsa

Payment Processing

POST URL https://testepay.homebank.kz/api/payment/cryptopay
POST URL https://epay-api.homebank.kz/payment/cryptopay

Request

Request Header:

Content-Type: application/json
Authorization: Bearer DCEB8O_ZM5U7SO_T_U5EJQ

Request Body:

{
  "amount":100,
  "currency":"KZT",
  "name":"JOHN JONSON",
"сryptogram":"UhYXAhYGeFA6srEVJ2V8Jtnnz6NzRwy8QDkCvEmJOcC6KyBP/Ce4SUM0A0My1zS1Iiur6AF0ajJwdi31EvrkRDBvzl2iLVKzvuAyusc5KuGpgxRhc6WXDhKkHV7J5Oew8uPMOfVbmXZ+Ypihos5ynSX7TnqQg1ImAmEISBxT+YU7jY68uxGhlehYMJ0lgS1Req4Z0BwCExBL2lwo05lmSMed69bEdBX552ue13zXjvTKIMrVj70hXIppXnxAE7haJfObuQzx2Ox+wM087kFPXfDX8Udlc6iRP2TxnRj7R1GnCTLvf3xlVU9ELzK+j91SPBQTvyEeyEvGMunjRch8lGXlogQreFSZmC5FUpfdfw6jYhl6lizUZYZzroN6/i5MILtV0US8zPFZTfozrCj8cvqw+J2W7yBywDiFoZG1teLDMIKIqTvkrmRL++Ji0psdHXl0z0ng/d0yTxzcBpPZ5V8VfNOexJJRZQUXBQqygAqqYninku/ls1NuTRMPeveyrgSMjQUVKU2W1izXdSreSdvaOio+1HJHNCZDwNn9yheTzbmuUsl5lhnsUGNT5gzMuYje8VfRYpsvG3Syz6nOijprG1wL3L/p5B/SZGrtaMMg/OdbD3mUWCSmat/V2v9RKHaeo5OHMnaVMTY5Tsqwa5JKBRP4ztRcjkjMRCBvS8c=",    
  "invoiceId":"000001",
  "description":"test payment",
  "accountId":"uuid000001",
  "email":"jj@example.com",
  "phone":"77777777777",
  "cardSave": true,
  "data": "{\"statement\":{\"name\":\"Arman Ali\",\"invoiceID\":\"80000016\"}}",
  "postLink":"https://testmerchant/order/1123",
  "failurePostLink":"https://testmerchant/order/1123/fail"
}

Payment Result without 3DSecure


HTTP/1.1 200 OK

 "id":"7943816b-58a8-47f6-a11e-67b63c4228c7",
  "amount": 100,
  "amountBonus":0,
  "currency":"KZT",
  "invoiceID":"938290483290",
  "invoiceIdAlt":"8564546",
  "accountID":"uuid000001",
  "phone":"77777777777",
  "email":"jj@example.com",
  "description":"test payment",
  "reference":"114537489258",
  "intReference":"435G34G34534T546",
  "secure3D":no,
  "secureDetails":" ", 
  "cardID":"111DFSDF-3F43-18V4-V34-ASD12342323",
  "language":"rus"
  "fee":0,
  "code":0,
  "status":"AUTH"
}

Unsuccessful payment operation result


HTTP/1.1 400 OK
{
"code": 487,
"message": " Not permitted to merchant",
"invoiceId": "8161284658525",
"id": "",
"reference": "",
"accountId": "uuid000001"
}

Payment operation result with 3DSecure

HTTP/1.1 200 OK

"id": "7943816b-58a8-47f6-a11e-67b63c4228c7",
    "accountId": "uuid000001",
    "amount": 10,
    "amountBonus": 0,
    "currency": "KZT",
    "description": "test payment",
    "email": "jj@example.com",
    "invoiceID": "123456813",
    "language": "RU",
    "phone": "77777777777",
    "reference": "",
    "intReference": "",
    "secure3D": {
        "paReq": "eJxVUl1TozAU/SsMrx1JSFuXdm7jsFZ23dbKmrbO+hYhCrYEDEFrf70JC3683XPunXPuPQmcHYq98yJUnZdy5voedh0hkzLN5ePM3ayjk8A9o7DOlBBzJpJGCQpXoq75o3Dy258741Sm14EUXbV5dC26bQGVCjijqhWtTaMWcVhjLWlgL0ecr5bxtxok1q4QMLgrh4iaRaln8I44PX1cM+/DHJ5pkNvh2yVrlJjYzwaetlASArg7o3Rd03MNW37/EOlXHEpA==",
        "md": "271710719-E54F6D8F865285D4",
        "action": "https://cardsecure.kkb.kz/CommerSafeACS/pa?id=YLcP2547mFFVw"
    },
    "secureDetails":"F", 
    "cardID": ""

After receiving the payment result with 3DSecure, the client needs to be redirected to the password input form.

To do this, the received parameters paReq, md, action are used.

In the TermUrl parameter, the address on which the merchant system will receive the 3DSecure password verification result needs to be used.

Example of building a form for redirecting the client:

<body  onload="javascript:OnLoadEvent();">
<FORM ACTION="<%=action%>" METHOD="post" NAME="ThreeDform" target="_self">
       <input name="PaReq" type="hidden" value="<%=paReq%>">
       <input name="MD" type="hidden" value="<%=md%>">
       <input name="TermUrl" type="hidden" value="https://merchantsite.com/3dRes">
</FORM>
       <div align="center"> 
            <h1>Дождитесь ответа! <br><br>
                 Жауабын күтіңіз!<br><br>
                 Wait for an answer!<br><br>                                                        
                </h1>
       </div>               
</body>
<SCRIPT>function OnLoadEvent () {
         document.forms[0].submit();
}

The result of 3DSecure verification obtained at the merchant's TermUrl:

PaRes: eJzNWVnT4jiy/SsdPY9Et3ewO6gvQt53bPD+5g3vNmCDjX/9FXxV1TXVPXHnzsONIYJATqcyU0rlOZLYO+Utz/lTnt5v+cfeyMcxLvJfquzLrxY45tc/Qp0HJ6UBIXZEC3EqspDgx/nXj/3r9fhWfKv8dpgvVMRu/efRq2VFBVDlkd/Gaug/sN/R3/E98u0RermlZdxPH/s4vbKK+UGSKLWl9sjXx32X3xT+w1QcXbcEhsYIFKewPfIp3iN/9rfur9YII1+q7MM9CLyv42mIMwEpTXPmM13cLamyob/skZfGPoun/ANHcQylcPoXDP0DJf+gtnvkLd9fXuZAN9yhbYyBbtE98qNsD2fplvfp84Ng6D3y/WmfL5ehz6EGHOb39h75M7xL3H+gP3wwCmOgbSjdO8HHfqq6n8Ki/sChrbd8P07xdB8/H+vOG631x//574XXT/OPfDv8D83MUpA== MD: 270469967-9CA5EC5779A3358E

Payment confirmation (sending the result of the 3DSecure password check)

URL POST /payment/confirm

Body
{
    "ID": "7943816b-58a8-47f6-a11e-67b63c4228c7",
    "PaRes": "/ZUo742DgULQ4CotpdByEwF6eQvOAFEggSRUtE+rfsh+A9pV1Uq7VX/B/aPaKfTyYOucmfHx8YzhaLOYa7cYJ34UVvWcYeoahjzy/HBa1YeD+kFZP2IwmMWINQf5OkYGbUwSd4qa71X1nt3HVeXqPK1PHHpCg1l+dHs84rlyszPVGWRpBrsLmNQ3KJA9lUoxn7lhysDlq+NmhxUKZvGwCGRHYYFxs8acRrd32rctWrQKZl4KfIQhdBfIGt32qSowLm6AZBHg0TpM4zuWt8pA9gTW8ZzN0nRZIQSX7p0RBGMjuAei4kC+rPTWCiVSZ+N7DEm/1LpqrobjktO6HNdaw/GNV+f2ZNCuAlEV4LkpMmrmLOmtpJlWpUArNAcki4O7UAZk3pTP+sCwVFfY3xLfAyC7HMsh7P3vGeBmGYWojgD5xOBhwpn4LV7FP7F9exBbTfzRxLN4kfjx7Zd4kfuDJv6Lrfgr15NKiUfpTp0D8vXak4YaA09lZ+3Lnj09871waEX3tU5wPUKPu5PuxJlTNZ",
	"MD": "271710719-E54F6D8F865285D4",
}

Response

Redirect Http code 200

Success https://epay.homebank.kz/payform/success.html Params amount currency invoiceID accountID description reference language cardid

Error https://epay.homebank.kz/payform/ invoiceID code message