Payment widget
Important: When studying this document, please take into account that using the Apple Pay payment method is not possible, since the payment tokenization policy does not allow the Apple Pay button to be displayed on the page that is opened using the widget.
When registered, you will be given data, that is needed when making the payment:
| TerminalID | Store identification |
| ClientID | Client Identification |
| ClientSecret | Secret Key |
Receiving a token for payment processing (for each operation it is necessary to obtain and use the original token)
TEST URL POST https://testoauth.homebank.kz/epay2/oauth2/token PROD URL POST https://epay-oauth.homebank.kz/oauth2/token
Request
Body: form-data
grant_type: "client_credentials" scope: "webapi usermanagement email_send verification statement statistics payment" client_id: "ClientID" client_secret: "ClientSecret" invoiceID: "Order number" secret_hash: "JDKCNDDGGDTPSKJD" amount: 100 curency: "KZT" terminal: "TerminalID"
| Field | Description |
|---|---|
| grant_type | Authorization type, client_credentials used to process payment |
| scope | Resource |
| client_id | Merchand Identification. Can be retrieved on the merchant account page, initially received when registering |
| client_secret | Merchant access key. Can be retrieved on the merchant account page, initially received when registering |
| invoiceID | Order number. Generated by the merchant. Must be unique for every new order |
| secret_hash | additional secret value(string) generated by the online store system which will be returned to Postlink |
| amount | Order amount |
| curency | Transaction currency |
| terminal | Salespoint identification. Can be retrieved on the merchant account page, initially generated when registered. |
Response
{ "access_token":"DCEB8O_ZM5U7SO_T_U5EJQ", "expires_in": 7200, "refresh_token":"", "scope":"webapi usermanagement email_send verification statement statistics payment"", "token_type":"Bearer" }
| Field | Description |
|---|---|
| access_token | A token that is used for payment processing. |
| expires_in | Expiry period of a token |
| refresh_token | Not used with this type of authorization |
| scope | Resource, payment type used for payment authorization |
| token_type | Authorization type |
Calling Widge
You need to connect a JS-Library on a page and make a call to halyk.showPaymentWidget().
URL: https://test-epay.homebank.kz/payform/payment-api.js
You must pass these parameters when calling halyk.showPaymentWidget(createPaymentObject(auth, invoiceId, amount), callBk)
var createPaymentObject = function(auth, invoiceId, amount) { var paymentObject = { invoiceId: "Номер заказа", invoiceIdAlt: "000001", backLink: "https://example.kz/success.html", failureBackLink: "https://example.kz/failure.html", postLink: "https://example.kz/", failurePostLink: "https://example.kz/order/1123/fail", language: "RUS", description: "Оплата в интернет магазине", accountId: "testuser1", terminal: "TerminalID", amount: 100, name: "Arman Ali", currency: "KZT", data: "{\"statement\":{\"name\":\"Arman Ali\",\"invoiceID\":\"80000016\"}}", }; paymentObject.auth = auth; return paymentObject; }; halyk.showPaymentWidget(createPaymentObject(auth, invoiceId, amount), callBk);
| Field | Description |
|---|---|
| invoiceId | The 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, then additional uniqueness must be maintained in the last 6 characters |
| invoiceIdAlt | An alternative order number, generated by the merchant, must be unique for each new order, from 6 to 15 digits |
| backLink | Link to get back to the store when payment succeeds. |
| failureBackLink | Link to get back to the store when payment fails. |
| postLink | Notification about the payment success. |
| failurePostLink | Notification about the payment failure. If not given, information would be sent back to the address that is specified in postLink. |
| language | Language rus/kaz/eng |
| description | Order description |
| accountId | Option field fir client identification number |
| terminal | Store identification |
| amount | Order amount |
| currency | Order currency |
| auth | Token / is transmitted completely as an object, all data received from epay upon request of the token |
| callBk | Send back the object { success: true | false } |
| data | Send back the object { success: true | false } |
halyk.showPaymentWidget()Post link
The message would be sent to the URL that is specified in postLink field
In case of success:
{ "accountId": "sad12eqsda", "amount": 100, "approvalCode": "157911", "cardId": "11f1111b-f151-6f11-e161-1111010a2111", "cardMask": "440043...2222", "cardType": "VISA", "code": "ok", "currency": "KZT", "dateTime": "2024-07-29T10:50:56.765674319+05:00", "description": "Arman Alimguzhinov", "email": "", "id": "1d1a11f1-1111-111c-1113b-e8340ce51111", "invoiceId": "191111111", "ip": "213.148.6.204", "ipCity": "", "ipCountry": "", "ipDistrict": "", "ipLatitude": 0, "ipLongitude": 0, "ipRegion": "", "issuer": "JSC KASPI BANK", "language": "RUS", "name": "STANDARD CARDHOLDER", "phone": "", "reason": "success", "reasonCode": 0, "reference": "411111111117", "secure": "no", "secureDetails":"F", "terminal": "67e34d63-102f-4bd1-898e-370781d0074d" }
In case of failure:
{
"id": "ffffffff-0000-000f-f000-00f0000f000f",
"dateTime": "2020-01-01T00:00:00.00000+06:00",
"invoiceId": "10000000001",
"invoiceIdAlt":"8564546",
"amount": 100,
"currency": "KZT",
"terminal": "67e34d63-102f-4bd1-898e-370781d0074d",
"accountId": "1",
"description": "Оплата в интернет магазине",
"language": "RU",
"cardMask": "4444...4444",
"cardType": "",
"issuer": "Halyk bank",
"reference": "",
"secure": "no",
"secureDetails":"F",
"tokenRecipient": "",
"code": "error",
"reason": "описание ошибки",
"reasonCode": -498,
"name": "CARD HOLDER",
"email": "ch@example.kz",
"phone": "77777777777",
"ip": "5.188.155.135",
"ipCountry": "Kazakhstan",
"ipCity": "Almaty",
"ipRegion": "",
"ipDistrict": "",
"ipLongitude": 76.9293,
"ipLatitude": 43.2638
}