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:

urlhttps://test-epay.homebank.kz
emailepay@halykbank.kz
passwordXZG1E@Mm
Client IDTest
clientSecretyF587AV9Ms94qN2QShFzVR3vFnWkhjbAK3sG
Terminal ID67e34d63-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 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
Account IDCustomer ID in the merchant's system or other additional parameter at the merchant's discretionOptional
emailCustomer emailOptional
phoneCustomer's phoneOptional
Link to the publicationLink to send the authorization result to the storeOptional
failurePostLinkLink for sending an unsuccessful authorization result or error information to the storeoptional
cardSaveParameter saving the card, true - save the card, false - do not save, logical typeRequired

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