Disclaimer
20 minutes after the QR code is generated, if the QR code has not been assigned the final status (PAID, REJECTED), the QR code will be canceled and cannot be paid, and the transaction will be marked as REJECTED
1. Token Generation
Request
TEST URL POST https://test-epay-oauth.epayment.kz/oauth2/token
PROD URL POST https://epay-oauth.homebank.kz/oauth2/token
Body: form-data
grant_type: "client_credentials"
client_id: "CLIENTID"
client_secret: "CLIENTSECRET"
scope: "webapi usermanagement email_send verification statement statistics payment"
terminal: "TERMINALID"
invoiceID: "invoiceID"
amount: "100"
currency: KZT
Incoming parameters
| Field | Description |
|---|
| grant_type | Request type, which indicates that client authentication is used. Value: client_credentials, required |
| client_id | is your unique client ID. Replace your client id with your real id, be sure |
| client_secret | Your client's secret key. Replace your client secret with your real secret, absolutely |
| scope | The access area required to perform the operation. For payments, specify: payment, required |
| terminal | The terminal ID in the UUID format. Replace your terminal id(uuid) to your real terminal ID, required |
| InvoiceID | The unique identifier of the invoice associated with the payment. Replace your invoice id with your real account ID, be sure |
| amount | The amount to be processed. Replace your amount with your actual amount, be sure |
| currency | The currency of the payment. Specify: KZT (tenge), required |
Response
{
"access_token": "access token",
"expires_in": "1200",
"refresh_token": "",
"scope": "payment",
"token_type": "Bearer"
}
Response data:
| Field | Description |
|---|
| access_token | Access token that you will use for authorization in further requests. Type: string |
| expires_in | Token lifetime in seconds. In this case: 1200 (20 minutes) |
| refresh_token | An update token that can be used to obtain a new access token. In this case, it's empty |
| scope | The access area that was requested. Here: payment |
| token_type | The type of token that will be used for authorization. Usually: Bearer |
2. QR Code Generation
Request
TEST URL POST https://test-epay-api.epayment.kz/payment/qr/generate
PROD URL POST https://epay-api.homebank.kz/payment/qr/generate
Authorization: The Bearer header with the access token obtained at the previous stage.
Payload:
Payload type: JSON
Body: form-data
{
"accountId": "your account id",
"payerEmail": "payer@mail.com",
"payerPhone": "87777777777",
"postLink": "https://example.com/postlink",
"failurePostLink": "https://example.com/failurepostlink",
"description": "payment purpose",
"data": "",
"language": "ru"
}
Incoming parameters
| Field | Description |
|---|
| accountId | Unique identifier of your account. Replace your account id with your real id (you can come up with any string value), optionally |
| payerEmail | Payer's email address. Specify your real address, for example: payer@mail.com , optional |
| payerPhone | The payer's phone number in string format. Specify a real number, for example: 87777777777, optional |
| postLink | URL for a callback after successful payment. Replace https://example.com/postlink to your real address, absolutely |
| failurePostLink | URL for a callback in case of a failed payment. Replace https://example.com/failurepostlink to your real address, absolutely |
| description | Payment purpose. Specify the text describing what the payment is being made for, for example: payment purpose, optional |
| data | Additional data that can be sent with the request. In this case, leave it blank if not required, optional |
| description | The language in which the information will be displayed. For example: ru for Russian |
Response
{
"qrcode": "qr code",
"homebankLink": "homebank deeplink",
"onlinebankLink": "online bank deeplink",
"status": "NEW",
"billNumber": 123456
}
Response:
| Field | Description |
|---|
| qrcode | Generated QR code for payment. Type: string |
| homebankLink | Deeplink to access the Homebank mobile app. Type: string |
| onlinebankLink | Deeplink to switch to online banking. Type: string |
| status | The current status of the QR code generation request. Here: NEW |
| billNumber | The unique account number associated with the transaction. Type: integer |
Possible error codes
| Field | Description |
|---|
| error code – 217. HTTP code – 400 | The terminal parameter was not passed when generating the token. |
| error code – 218. HTTP code – 400 | The InvoiceID parameter was not passed when generating the token |
| error code – 563. HTTP code – 400 | Error in receiving terminal data via the terminal id transmitted in the token |
| error code – 219. HTTP code – 400 | The pay_qr_local parameter is disabled on the terminal |
| error code – 1531. HTTP code – 400 | Error parsing the structure passed to the payload |
| error code – 220. HTTP code – 400 | Error generating QR code |
3. Getting the payment status
Request
TEST URL GET https://test-epay-api.epayment.kz/qr
PROD URL GET https://epay-api.homebank.kz/qr
Authorization: The Bearer header with the access token, , used when generating the QR code.
Payload: Empty.
Response
{
"qrcode": "00020101021227400012KZ.HALYKBANK0108HSBKKZKX02089830130028660011477859186730120KZ8160101310001554340208983013000301N0501006010520447845303398540420005802KZ5907KINO.KZ6006ALMATY62380111477859186730803191101204074000842363046CA2",
"status": "NEW",
"reference": "",
"cardId": "",
"cardType": "",
"cardMask": "",
"trType": "LOCALQR",
"secure3D": false,
"openwayId": "",
"issuer": "HSBKKZKX",
"issuerBankCountry": "KZ",
"fee": 0,
"amount": 2000,
"currency": "KZT",
"paymentChannel": "",
"errDescription": "",
"retCode": ""
}
Response data:
| Field | Description |
|---|
| qrcode | A string representing a QR code |
| status | The current status of the QR payment. Possible values: NEW – status when generating a QR code; SCANNED - status when scanning in the Halyk Super App; BLOCKED – status when making a payment, funds are blocked, not final; PAID or REJECTED – status upon successful payment or payment error; |
| reference | Link to additional information (if available) |
| CardID | Card ID (if applicable) |
| cardType | Card type (if applicable) |
| cardMask | Card mask (if applicable) |
| trType | The type of transaction. In this case: LOCALQR |
| secure3D | Indicates whether 3D Secure is required for this transaction. Value: false |
| openwayId | Route ID (if applicable) |
| issuer | ID of the card issuer |
| issuerBankCountry | Country of the issuing bank. For example: KZ |
| fee | Transaction fee. Value: 0 |
| amount | The amount of the payment. For example: 2000 |
| currency | The currency of the payment. For example: KZT |
| paymentChannel | Payment channel (if applicable) |
| errDescription | Error description (if applicable) |
| retCode | Refund code (if applicable) |
Refund QR payment
1. Token Generation
TEST URL POST https://test-epay-oauth.epayment.kz/oauth2/token
PROD URL POST https://epay-oauth.homebank.kz/oauth2/token
Body: form-data
grant_type: "client_credentials"
client_id: "CLIENTID"
client_secret: "CLIENTSECRET"
scope: "webapi usermanagement email_send verification statement statistics payment"
currency: KZT
Incoming parameters
| Field | Description |
|---|
| grant_type | Request type, which indicates that client authentication is used. Value: client_credentials, required |
| client_id | is your unique client ID. Replace your client id with your real id, be sure |
| client_secret | Your client's secret key. Replace your client secret with your real secret, absolutely |
| scope | The access area required to perform the operation. For payments, specify: payment, required |
Response
{
"access_token": "access token",
"expires_in": "1200",
"refresh_token": "",
"scope": "payment",
"token_type": "Bearer"
}
Response data:
| Field | Description |
|---|
| access_token | The access token that you will use for authorization in further requests. Type: string |
| expires_in | Token lifetime in seconds. In this case: 1200 (20 minutes) |
| refresh_token | An update token that can be used to obtain a new access token. In this case, it's empty |
| scope | The access area required to perform the operation. For payments, specify: payment |
| token_type | The type of token that will be used for authorization. Usually: Bearer |
2. Making a refund
Learn more: https://epayment.kz/docs/vozvrat-chastichnyi-vozvrat
Description of the QR payment check status
[https://epayment.kz/docs/check-status-payment]
Information about the payment or refund is received in the same way as in the documentation, with the exception of one field in the response. In the transaction object, an additional “PaymentType” field will be given for QR transactions: “QR".