Google Pay by API

To work through the API, the merchant needs to register in the GOOGLE system and be able to decrypt the data that will later need to be transmitted to the EPAY system To work using the Pay by GOOGLE method, the company needs PCI DSS certification

Integration is possible only in the product environment

ATTENTION:

PAN_ONLY: This authentication method is associated with payment cards stored on file with the user's Google Account. Returned payment data includes personal account number (PAN) with the expiration month and the expiration year

CRYPTOGRAM_3DS: This authentication method is associated with cards stored as Android device tokens. Returned payment data includes a 3-D Secure (3DS) cryptogram generated on the device

  • TerminalID – store ID
  • ClientID – client ID
  • clientSecret – secret key

Data for test payments:

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

Getting a token for making a payment (for each operation, you need to receive and use the original 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: "Order number"
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"
}

Incoming parameters:

Field nameDescriptionRequired/optional
amountPayment amountRequired
currencyCurrencyRequired
nameCardholder nameRequired
cryptogramEncrypted payment card parametersRequired
InvoiceIDOrder number in the storeRequired
descriptionThis field contains information about the goods or services for which payment is made
AccountIdCustomer ID in the merchant's system or other additional parameter at the merchant's discretionoptional
emailClient's emailOptional
phoneClient's phoneOptional
postLinkLink for sending the authorization result to the storeOptional
failurePostLinkLink for sending an unsuccessful authorization result or error information to the store.optional
cardSaveParameter saving the card, true - save the card, false - do not save, boolean typeRequired

Cryptogram preparation:

Cryptogram structure:

{
hpan string
expDate string
cvc string
terminalId string
}

Example:
{
"hpan":"GOOGLEToken",
"expDate":"mmyy",
"cvc":"",
"terminalId":"67e34d63-102f-4bd1-898e-370781d0074d"
}


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

Making a payment:

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": 10.0,
"currency": "KZT",
"name": "Arman Ali",
"cryptogramGooglePay": "Decrypted cryptograms from Google",
"cryptogram": "jkasDHJIHUIHDUIOHUI23HDUI2NUIBN2I23NDJIN2OIEN2IODN0I23J0M230IDJMI023MDKDMKLSFJSDF651454564SDFIOHF984N98HFIJ2HF "
"InvoiceID": "163637162556226",
"description": "Payment via Google",
"AccountId": "",
"email": "ch.kabykenov@gmail.com ",
"phone": "+77778871188",
"backLink": "http://example/backLink ",
"failureBackLink": "http://example/failureBackLink ",
"postLink": "http://example/postLink ",
"failurePostLink": "http://example/failurePostLink ",
"PaymentType": "GooglePay"
}


Result of payment operation without 3DSecure

HTTP/1.1 200 OK

{
"id": "7943816b-58a8-47f6-a11e-67b63c4228c7",
"amount": 100,
"currency": "KZT",
"invoiceID": "938290483290",
"accountID": "uuid000001",
"phone": "77777777777",
"email": "jj@example.com",
"description": "test payment",
"reference": "114537489258",
"language": "rus"
}

Result of unsuccessful payment operation

HTTP/1.1 400 OK

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


Status Code

BUYER_ACCOUNT_ERROR.

The current Google user cannot provide payment information.

DEVELOPER_ERROR.

The passed parameter has an incorrect format. An error message may appear in the browser console for all configured environments.

MERCHANT_ACCOUNT_ERROR.

A site accessing the Google Pay API does not have the necessary permission. This may be due to both an incorrect setup and an incorrect merchant ID specified in the request. Check the statusMessage field for more details. If you still have problems, please contact support.

INTERNAL_ERROR. General server error.

Result of payment operation 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"
},
"cardID": ""


After receiving the result of the payment with 3DSecure, 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 TermUrl parameter, you must use the address to which the merchant's system will receive the result of the 3DSecure check. 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>Wait for the answer! <br><br>
Zhauabyn kutiniz!<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 3DSecure password verification)

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