Apple Pay using the API

To work through the API, the merchant needs to register in the Apple system and be able to decrypt data that will later need to be transmitted to our system

Integration can only be carried out in a production environment

TerminalID – store ID
Customer ID – Customer ID
Client secret – Secret key

Data for test payments:


url	https://test-epay.homebank.kz
email	epay@halykbank.kz
password	XZG1E@Mm
Client ID	Test
clientSecret	yF587AV9Ms94qN2QShFzVR3vFnWkhjbAK3sG
Terminal ID	67e34d63-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 https://epay-oauth.homebank.kz/oauth2/token

Request

grant_type: "client_credentials"
scope: "webapi usermanagement email_send statement verification payment statistics"
client_id: "Client ID"
client_secret: "Client secret"
Invoice ID: "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 statement for checking payment statistics",
"token_type": "Bearer"
}

Incoming parameters

Field name	Description	Required/optional
amount	Payment amount	Required
currency	Currency	Required
name	Cardholder name	Required
cryptogram	Encrypted payment card parameters	Required
InvoiceID	Order number in the store	required
description	This field contains information about the goods or services for which payment is made
Account ID	Customer ID in the merchant's system or other additional parameter at the merchant's discretion	Optional
email	Customer email	Optional
phone	Customer's phone	Optional
Link to the publication	Link to send the authorization result to the store	Optional
failurePostLink	Link for sending an unsuccessful authorization result or error information to the store	optional
cardSave	Parameter saving the card, true - save the card, false - do not save, logical type	Required

Cryptogram preparation

Cryptogram structure:

{
hpan string
expDate string
cvc string
terminalId string
}

Еxample:

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

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

Making a payment

URL OF THE PUBLICATION 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",
"cryptogramApplePay": "Decrypted cryptogram from Apple",
"cryptogram": "jkasDHJIHUIHDUIOHUI23HDUI2NUIBN2I23NDJIN2OIEN2IODN0I23J0M230IDJMI023MDKDMKLSFJSDF651454564SDFIOHF984N98HFIJ2HF "
"invoiceID": "163637162556226",
"description": "Payment via ApplePay",
"account ID": "",
"email": "armanali@gmail.com ",
"phone": "+77771232380",
"Backlink": "http://example/backLink ",
"failureBackLink": "http://example/failureBackLink ",
"postLink": "http://example/postLink ",
"failurePostLink": "http://example/failurePostLink ",
"paymentType": "ApplePay"
}

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",
"link":"114537489258",
"language": "rus"
}

Result of unsuccessful payment

HTTP/1.1 400 OK

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

Result of the payment transaction with 3DSecure

{
"id": "7943816b-58a8-47f6-a11e-67b63c4228c7",
"AccountId": "",
"amount": 100,
"accumtBonus": 0,
"currency": "KZT",
"description": "Order payment 938290483290",
"email": "",
"InvoiceID": "938290483290",
"invoiceIdAlt":"8564546",
"language": "RU",
"phone": "",
"reference": "",
    "intReference": "",
    "secure3D": {
    "paReq": "eyJtZXNzYWdlVHlwZSI2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiIyMDFiZDlmYy1kM2IzLTQ4YjUtYWRiNy1jYjM1YT6IjA1In0",
        "md": "MjAxYmQ5ZmsadasdtY2IzNWE1NjFhM2Mw",
        "action": "https://epay-proxy.homebank.kz/"
    },
    "cardID": "",
    "fee": 0
}

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. 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>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: MjAxYmQ5ZmsadasdtY2IzNWE1NjFhM2Mw

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

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