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


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:


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


The 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 data:


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

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

the error code is 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:


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; 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"
terminal: "TERMINALID"
invoiceID: "invoiceID"
amount: "100"
currency: KZT

Incoming parameters


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:


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

TEST POST URL https://test-epay-api.epayment.kz/operations/:id/refund 
PROD URL POST https://epay-api.homebank.kz/operation/:id/refund
The ID specified in the URL is the transaction ID that you received earlier in the postlink after successful payment or when requesting the transaction status.

Body: form-data

{
  "amount": 100,
  "purpose": "refund purpose"
}

Incoming parameters


amount	Refund amount, if the amount is not transferred, the request will be identified as a full refund, optional
payerEmail	Reason for the refund, optional

Response

{
  "code": 3225,
  "externalID": "",
  "message": "in progress"
}

Response data:


code	Response code
message	Message with information about the refund status

Additionally: When sending a refund request, the refund is only initiated, but not carried out immediately. In response to a successful refund request, you will receive the message “in_progress”, the refund status can be obtained via check status.

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".