Дисклеймер

Через 20 минут с момента генерации QR кода в случае если QR коду не присвоился финальный статус (PAID, REJECTED), то QR код будет отменен и не сможет быть оплачен и транзакция будет помечена как отказанная (REJECTED)

1. Генерация токена

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

Входящие параметры

Response

{
    "access_token": "access token",
    "expires_in": "1200",
    "refresh_token": "",
    "scope": "payment",
    "token_type": "Bearer"
}

Данные ответа:

2. Генерация QR

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: заголовок Bearer с токеном доступа, полученным на предыдущем этапе.
Payload:
Тип payload: 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"
}

Входящие параметры

Response

{
  "qrcode": "qr code",
  "homebankLink": "homebank deeplink",
  "onlinebankLink": "online bank deeplink",
  "status": "NEW",
  "billNumber": 123456
}

Данные ответа:

Возможные коды ошибок

• код ошибки – 217. HTTP код – 400:

Параметр terminal не передан при генерации токена

• код ошибки – 218. HTTP код – 400:

Параметр invoiceID не передан при генерации токена

• код ошибки – 563. HTTP код – 400:

Ошибка получения данных о терминале через terminal id переданный в токене

• код ошибки – 219. HTTP код – 400:

Параметр pay_qr_local отключен на терминале

• код ошибки – 1531. HTTP код – 400:

Ошибка парсинга структуры переданной в payload

• код ошибки – 220. HTTP код – 400:

Ошибка при генерации QR

3. Получение статуса платежа

Request

TEST URL GET https://test-epay-api.epayment.kz/qr  
PROD URL GET https://epay-api.homebank.kz/qr 
Authorization: заголовок Bearer с токеном доступа, , использованным при генерации QR.
Payload: Пустой.

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": ""
}

Данные ответа:

Возврат QR платежа

1. Генерация токена

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

Входящие параметры

Response

{

    "access_token": "access token",
    "expires_in": "1200",
    "refresh_token": "",
    "scope": "payment",
    "token_type": "Bearer"
}

Данные ответа:

2. Проведение возврата

Подробнее: https://epayment.kz/docs/vozvrat-chastichnyi-vozvrat

TEST URL POST https://test-epay-api.epayment.kz/operations/:id/refund 
PROD URL POST https://epay-api.homebank.kz/operation/:id/refund

Id указанный в URL это id транзакции который вы получили ранее в postlink после удачной оплаты или при запросе статуса транзакции.

Body: form-data

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

Входящие параметры

Response

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

Данные ответа:

Дополнительно: При отправке запроса на возврат, возврат лишь инициируется, но не проводится сразу. В ответе на успешный запрос на возврат вы получите сообщение “in_progress”, статус возврата можно получить через check status.

Описание check status QR платежа

https://epayment.kz/docs/check-status-payment

Получение информации о платеже или возврате происходит точно также как в документации, за исключением одного поля в ответе. В объекте transaction для QR’ных транзакций будет отдаваться дополнительное поле “paymentType”: “QR”.