A service for checking the validity of the card and, if necessary, saving it

Receiving a token for making a payment (for each operation, you must receive and use the original token)

PUBLISHING WITH A SIMPLE URL https://testoauth.homebank.kz/epay2/oauth2/token
PUBLISHING WITH A SIMPLE URL https://epay-oauth.homebank.kz/oauth2/token

Request

grant_type: "client_credentials"
scope: "webapi usermanagement email_send verification statement statistics payment"
client_id: "halykfinanceUSD"
client_secret: "U01gQZVL##lJ$NhJ"
invoiceID: "Номер заказа"
amount: 0
currency: "USD"
terminal: "d9d7978c-d6ee-4ec0-8cda-165251a4bf16"

The answer

{
"access_token": "DCEB8O_ZM5U7SO_T_U5EJQ",
"expires_in": 7200,
"scope": "webapi usermanagement manages email intended for data transmission",
"token_type": "Representative".
}

Incoming parameters

Field name	Description	Required/Optional
amount	Amount that accounts for all time 0	Required
currency	The currency of the whole world is USD	Required /
name	I'm holding the cards	The designation /
cryptogram	Encrypted parameters of the paid card	The designation
Invoice ID	The order number generated by the user can be unique for each new order, from 6 to 15 years old. If you want someone to say that you have more than 6 words, then you need more time to get together with those 6 words_________________________________	Explanatory
Invoicing	Indicating the number generated by the user, maybe for each new order, from 6 to 15 years old	Required /
description	In this case, information is provided about the product or services for which payment is made	Explanatory note
AccountId	User ID connected to the system computer, or a simple user interface for viewing data.	Automatic /
Email	Client's email address	Desired
phone / Desired client	Desired /
Mail link	Link to send for authorization in the store	Free of charge /
failurePostLink	Link to opt out of a simple online authorization setup to send to the store	For free /
cardsave	The parameter displays the map, true - displays the map, false - does not display, logical type	General
data	Fully distributed according to the request	Preferably
qrReference	the number of the payment made via qr, in case the payment was made without qr, the field value will be empty	Required
accumtBonus	a field that reflects the amount of bonuses that was used by the client when paying with bonuses. If the card is saved, this value will always be 0	Required
ip	the IP address where the request was made from	Required
ipCountry	сountry name	Required
ipCity	name of the city	Required
ipRegion	name of the region	Required
ipDistrict	name of the district	Required
ipLatitude	latitude	Required
ipLongitude	longitude	Required
issuerBankCountry	country of the issuing bank	Required

Preparing the cryptogram

Cryptogram structure:

{
hpan string
expDate string 
cvc string
terminalId string
}

Example:

{
"hpan": "4003032704547597",
"Accessed date": "1022",
"cvc": "636",
"User ID": "0d4d345e-8566-43bd-b046-028b5aee6406".
}

The structure should be focused on a potential user of the business class, who will find the right address https://epay-api.homebank.kz/public.rsa https://testepay.homebank.kz/api/public.rsa

Making a payment

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

Request

Request header:

Type used: application/json
Author: our representative is DCEB8O_ZM5U7SO_T_U5EJQ

Request body:

{
  "amount":0,
  "currency":"USD",
  "name":"JON JONSON",
  "cryptogram":"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,
  "paymentType": "cardVerification",
  "data": "{\"statement\":{\"name\":\"Arman     Ali\",\"invoiceID\":\"80000016\"}}",
  "postLink":"https://testmerchant/order/1123",
  "failurePostLink":"https://testmerchant/order/1123/fail"
}

The result of a successful payment operation without 3D Secure


HTTP/1.1 200 OK

{
  "id":"7943816b-58a8-47f6-a11e-67b63c4228c7",
  "accountID": "uuid000001",
  "amount": 0,
  "amountBonus": 0,
  "currency": "USD",
  "description": "test payment",
  "email": "jj@example.com",
  "invoiceID": "938290483290",
  "language": "RUS"
  "phone":"77777777777",
  "reference": "114537489258",
  "intReference": "435G34G34534T546",
  "secure3D": null,
  "cardID": "111DFSDF-3F43-18V4-V34-ASD12342323",
  "fee": 0,
  "code": 0,
  "status":"VERIFIED",
  "secureDetails": "",
  "qrReference": "",
  "ip": "172.30.212.37",
  "ipCity": "",
  "ipCountry": "",
  "ipDistrict": "",
  "ipLatitude": 0,
  "ipLongitude": 0,
  "ipRegion": "",
  "issuerBankCountry": "KAZ"

}

The result of a failed payment transaction


HTTP/1.1 400 OK

{
"code": 487,
"message": " Not permitted to merchant",
"invoiceId": "8161284658525",
"id": "",
"reference": "",
"accountId": "uuid000001"
}

The result of the payment operation with 3D Secure

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

After receiving the result of the payment with 3D Secure, it is necessary to redirect the client to the password entry form.

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

In the Term Url parameter, you must use the address to which the merchant system will receive the result of the 3D Secure check. the password.

Example of building a form for redirecting a 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 the 3DSecure check received on 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 3D Secure password verification)

URL POST https://epay-api.homebank.kz/payments/confirm?Access=:token

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

The result of a successful operation


HTTP/1.1 200 OK

{
  "id": "7943816b-58a8-47f6-a11e-67b63c4228c7",
  "accountID": "uuid000001",
  "amount": 0,
  "amountBonus": 0,
  "currency": "USD",
  "description": "test payment",
  "email": "jj@example.com",
  "invoiceID": "938290483290",
  "language": "RUS"
  "phone": "77777777777",
  "reference": "114537489258",
  "intReference": "435G34G34534T546",
  "secure3D": null,
  "cardID": "111DFSDF-3F43-18V4-V34-ASD12342323",
  "fee":0,
  "code":0,
  "status":"VERIFIED",
  "secureDetails": "F",
  "qrReference": "",
  "ip": "172.30.212.37",
  "ipCity": "",
  "ipCountry": "",
  "ipDistrict": "",
  "ipLatitude": 0,
  "ipLongitude": 0,
  "ipRegion": "",
  "issuerBankCountry": "KAZ"
}