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

FieldDescription
grant_typeRequest type, which indicates that client authentication is used. Value: client_credentials, required
client_idis your unique client ID. Replace your client id with your real id, be sure
client_secretYour client's secret key. Replace your client secret with your real secret, absolutely
scopeThe access area required to perform the operation. For payments, specify: payment, required
terminalThe terminal ID in the UUID format. Replace your terminal id(uuid) to your real terminal ID, required
InvoiceIDThe unique identifier of the invoice associated with the payment. Replace your invoice id with your real account ID, be sure
amountThe amount to be processed. Replace your amount with your actual amount, be sure
currencyThe 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:

FieldDescription
access_tokenAccess token that you will use for authorization in further requests. Type: string
expires_inToken lifetime in seconds. In this case: 1200 (20 minutes)
refresh_tokenAn update token that can be used to obtain a new access token. In this case, it's empty
scopeThe access area that was requested. Here: payment
token_typeThe 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

FieldDescription
accountIdUnique identifier of your account. Replace your account id with your real id (you can come up with any string value), optionally
payerEmailPayer's email address. Specify your real address, for example: payer@mail.com , optional
payerPhoneThe payer's phone number in string format. Specify a real number, for example: 87777777777, optional
postLinkURL for a callback after successful payment. Replace https://example.com/postlink to your real address, absolutely
failurePostLinkURL for a callback in case of a failed payment. Replace https://example.com/failurepostlink to your real address, absolutely
descriptionPayment purpose. Specify the text describing what the payment is being made for, for example: payment purpose, optional
dataAdditional data that can be sent with the request. In this case, leave it blank if not required, optional
descriptionThe 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:

FieldDescription
qrcodeGenerated QR code for payment. Type: string
homebankLinkDeeplink to access the Homebank mobile app. Type: string
onlinebankLinkDeeplink to switch to online banking. Type: string
statusThe current status of the QR code generation request. Here: NEW
billNumberThe unique account number associated with the transaction. Type: integer

Possible error codes

FieldDescription
error code – 217. HTTP code – 400The terminal parameter was not passed when generating the token.
error code – 218. HTTP code – 400The InvoiceID parameter was not passed when generating the token
error code – 563. HTTP code – 400Error in receiving terminal data via the terminal id transmitted in the token
error code – 219. HTTP code – 400The pay_qr_local parameter is disabled on the terminal
error code – 1531. HTTP code – 400Error parsing the structure passed to the payload
error code – 220. HTTP code – 400Error 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:

FieldDescription
qrcodeA string representing a QR code
statusThe 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;
referenceLink to additional information (if available)
CardIDCard ID (if applicable)
cardTypeCard type (if applicable)
cardMaskCard mask (if applicable)
trTypeThe type of transaction. In this case: LOCALQR
secure3DIndicates whether 3D Secure is required for this transaction. Value: false
openwayIdRoute ID (if applicable)
issuerID of the card issuer
issuerBankCountryCountry of the issuing bank. For example: KZ
feeTransaction fee. Value: 0
amountThe amount of the payment. For example: 2000
currencyThe currency of the payment. For example: KZT
paymentChannelPayment channel (if applicable)
errDescriptionError description (if applicable)
retCodeRefund 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

FieldDescription
grant_typeRequest type, which indicates that client authentication is used. Value: client_credentials, required
client_idis your unique client ID. Replace your client id with your real id, be sure
client_secretYour client's secret key. Replace your client secret with your real secret, absolutely
scopeThe 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:

FieldDescription
access_tokenThe access token that you will use for authorization in further requests. Type: string
expires_inToken lifetime in seconds. In this case: 1200 (20 minutes)
refresh_tokenAn update token that can be used to obtain a new access token. In this case, it's empty
scopeThe access area required to perform the operation. For payments, specify: payment
token_typeThe 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".