Платеж через API

Для работы через API компании необходимо наличие сертификации PCI DSS

При регистрации вам будут выданы данные, которые нужно будет использовать при проведении платежа:

TerminalID – идентификатор магазина
ClientID – идентификатор клиента
ClientSecret – секретный ключ

Получение токена для проведения оплаты (для каждой операции необходимо получать и использовать оригинальный токен)

TEST URL POST https://testoauth.homebank.kz/epay2/oauth2/token
PROD URL POST https://epay-oauth.homebank.kz/oauth2/token

Запрос

grant_type: "client_credentials"
scope: "webapi usermanagement email_send verification statement statistics payment"
client_id: "ClientID"
client_secret: "ClientSecret"
invoiceID: "Номер заказа"
secret_hash: "JDKCNDDGGDTPSKJD"
amount: 100
currency: "KZT"
terminal: "67e34d63-102f-4bd1-898e-370781d0074d"

Ответ

{
  "access_token": "DCEB8O_ZM5U7SO_T_U5EJQ",
  "expires_in": 7200,
  "scope": "webapi usermanagement email_send verification statement statistics payment",
  "token_type": "Bearer"
}

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

Название поля	Описание	Обязательное/не обязательно
amount	Cумма платежа	Oбязательное
currency	Валюта	Oбязательное
name	Имя держателя карты	Oбязательное
сryptogram	Закриптованные параметры платежной карты	Oбязательное
invoiceId	Номер заказа, генерируется коммерсантом, должен быть уникальный для каждого нового заказа, от 6 до 15 цифр. Если ваш номер заказа содержит более 6 символов, то дополнительно уникальность должна соблюдаться по последним 6ти символам	Oбязательное
invoiceIdAlt	Номер заказа, генерируется коммерсантом, должен быть уникальный для каждого нового заказа, от 6 до 15 цифр	Hеобязательно
description	В данном поле передается информация о товарах или услугах, за которые производится оплата	Oбязательное
accountId	Идентификатор клиента в системе коммерсанта или другой дополнительные параметр на усмотрение коммерсанта	Hеобязательно
email	Email клиента	Hеобязательное
phone	Tелефон клиента	Hеобязательно
postLink	Линк для отправки результата авторизации в магазин, на него будет передан secret_hash	Oбязательно
failurePostLink	Линк для отправки неудачного результата авторизации либо информации об ошибке в магазин	Hеобязательно
cardsave	Параметр сохранение карты, true - сохранить карту, false - не сохранять, boolean type	Oбязательное
data	Дополнительное поле транслируется в отчете при заполнении	Hеобязательно

Подготовка криптограммы

Структура криптограммы:

{
  hpan string
  expDate string
  cvc string
  terminalId string
}

Пример:

{
 "hpan":"4003032704547597",
 "expDate":"1022",
 "cvc":"636",
 "terminalId":"67e34d63-102f-4bd1-898e-370781d0074d"
}

Структура должна быть зашифрована при помощи публичного RSA-ключа, который доступен по адресу https://epay-api.homebank.kz/public.rsa https://testepay.homebank.kz/api/public.rsa

Проведение платежа

POST URL https://testepay.homebank.kz/api/payment/cryptopay
POST URL https://epay-api.homebank.kz/payment/cryptopay

Запрос

Заголовок запроса:

Content-Type: application/json
Authorization: Bearer DCEB8O_ZM5U7SO_T_U5EJQ

Тело запроса:

{
  "amount":100,
  "currency":"KZT",
  "name":"JON JONSON",
"cryptogram":"UhYXAhYGeFA6srEVJ2V8Jtnnz6NzRwy8QDkCvEmJOcC6KyBP/Ce4SUM0A0My1zS1Iiur6AF0ajJwdi31EvrkRDBvzl2iLVKzvuAyusc5KuGpgxRhc6WXDhKkHV7J5Oew8uPMOfVbmXZ+Ypihos5ynSX7TnqQg1ImAmEISBxT+YU7jY68uxGhlehYMJ0lgS1Req4Z0BwCExBL2lwo05lmSMed69bEdBX552ue13zXjvTKIMrVj70hXIppXnxAE7haJfObuQzx2Ox+wM087kFPXfDX8Udlc6iRP2TxnRj7R1GnCTLvf3xlVU9ELzK+j91SPBQTvyEeyEvGMunjRch8lGXlogQreFSZmC5FUpfdfw6jYhl6lizUZYZzroN6/i5MILtV0US8zPFZTfozrCj8cvqw+J2W7yBywDiFoZG1teLDMIKIqTvkrmRL++Ji0psdHXl0z0ng/d0yTxzcBpPZ5V8VfNOexJJRZQUXBQqygAqqYninku/ls1NuTRMPeveyrgSMjQUVKU2W1izXdSreSdvaOio+1HJHNCZDwNn9yheTzbmuUsl5lhnsUGNT5gzMuYje8VfRYpsvG3Syz6nOijprG1wL3L/p5B/SZGrtaMMg/OdbD3mUWCSmat/V2v9RKHaeo5OHMnaVMTY5Tsqwa5JKBRP4ztRcjkjMRCBvS8c=",    
  "invoiceId":"000001",
  "invoiceIdAlt":"8564546",
  "description":"test payment",
  "accountId":"uuid000001",
  "email":"jj@example.com",
  "phone":"77777777777",
  "cardSave": true,
  "data": "{\"statement\":{\"name\":\"Arman     Ali\",\"invoiceID\":\"80000016\"}}",
  "postLink":"https://testmerchant/order/1123",
  "failurePostLink":"https://testmerchant/order/1123/fail"
}

Результат успешной операции по оплате без 3DSecure


HTTP/1.1 200 OK

{
  "id": "7943816b-58a8-47f6-a11e-67b63c4228c7",
  "amount": 100,
  "amountBonus": 0,
  "currency": "KZT",
  "invoiceID": "938290483290",
  "invoiceIdAlt": "8564546",
  "accountID": "uuid000001",
  "phone": "77777777777",
  "email": "jj@example.com",
  "description": "test payment",
  "reference": "114537489258",
  "intReference": "435G34G34534T546",
  "secure3D": no,
  "secureDetails": " ", 
  "cardID": "111DFSDF-3F43-18V4-V34-ASD12342323",
  "language": "rus"
  "fee":0,
  "code": 0,
  "status": "AUTH"
}

Результат неуспешной операции по оплате


HTTP/1.1 400 OK

{
"code": 487,
"message": " Not permitted to merchant",
"invoiceId": "8161284658525",
"id": "",
"reference": "",
"accountId": "uuid000001"
}

Результат операции по оплате с 3DSecure

HTTP/1.1 200 OK

"id": "7943816b-58a8-47f6-a11e-67b63c4228c7",
    "accountId": "uuid000001",
    "amount": 10,
    "amountBonus": 0,
    "currency": "KZT",
    "description": "test payment",
    "email": "jj@example.com",
    "invoiceID": "123456813",
    "invoiceIdAlt":"8564546",
    "language": "RU",
    "phone": "77777777777",
    "reference": "",
    "intReference": "",
    "secure3D": {
        "paReq": "eJxVUl1TozAU/SsMrx1JSFuXdm7jsFZ23dbKmrbO+hYhCrYEDEFrf70JC3683XPunXPuPQmcHYq98yJUnZdy5voedh0hkzLN5ePM3ayjk8A9o7DOlBBzJpJGCQpXoq75o3Dy258741Sm14EUXbV5dC26bQGVCjijqhWtTaMWcVhjLWlgL0ecr5bxtxok1q4QMLgrh4iaRaln8I44PX1cM+/DHJ5pkNvh2yVrlJjYzwaetlASArg7o3Rd03MNW37/EOlXHEpA==",
        "md": "271710719-E54F6D8F865285D4",
        "action": "https://cardsecure.kkb.kz/CommerSafeACS/pa?id=YLcP2547mFFVw"
    },
    "cardID": ""

После получения результата по оплате с 3DSecure необходимо переадресовать клиента на форму ввода пароля.

Для этого используются полученные параметры: paReq, md, action.

В параметре TermUrl необходимо использовать адрес, на который система мерчанта получит результат проверки 3DSecure. пароля.

Пример построения формы для перенаправления клиента:

<body  onload="javascript:OnLoadEvent();">
<FORM ACTION="<%=action%>" METHOD="post" NAME="ThreeDform" target="_self">
       <input name="PaReq" type="hidden" value="<%=paReq%>">
       <input name="MD" type="hidden" value="<%=md%>">
       <input name="TermUrl" type="hidden" value="https://merchantsite.com/3dRes">
</FORM>
       <div align="center"> 
            <h1>Дождитесь ответа! <br><br>
                 Жауабын күтіңіз!<br><br>
                 Wait for an answer!<br><br>                                                        
                </h1>
       </div>               
</body>
<SCRIPT>function OnLoadEvent () {
         document.forms[0].submit();
}

Результат проверки 3DSecure, получаемый на TermUrl мерчанта:

PaRes: eJzNWVnT4jiy/SsdPY9Et3ewO6gvQt53bPD+5g3vNmCDjX/9FXxV1TXVPXHnzsONIYJATqcyU0rlOZLYO+Utz/lTnt5v+cfeyMcxLvJfquzLrxY45tc/Qp0HJ6UBIXZEC3EqspDgx/nXj/3r9fhWfKv8dpgvVMRu/efRq2VFBVDlkd/Gaug/sN/R3/E98u0RermlZdxPH/s4vbKK+UGSKLWl9sjXx32X3xT+w1QcXbcEhsYIFKewPfIp3iN/9rfur9YII1+q7MM9CLyv42mIMwEpTXPmM13cLamyob/skZfGPoun/ANHcQylcPoXDP0DJf+gtnvkLd9fXuZAN9yhbYyBbtE98qNsD2fplvfp84Ng6D3y/WmfL5ehz6EGHOb39h75M7xL3H+gP3wwCmOgbSjdO8HHfqq6n8Ki/sChrbd8P07xdB8/H+vOG631x//574XXT/OPfDv8D83MUpA== MD: 270469967-9CA5EC5779A3358E

Подтверждение платежа (отправка результата проверки 3DSecure пароля)

URL POST /payment/confirm

Body
{
    "ID": "7943816b-58a8-47f6-a11e-67b63c4228c7",
    "PaRes": "/ZUo742DgULQ4CotpdByEwF6eQvOAFEggSRUtE+rfsh+A9pV1Uq7VX/B/aPaKfTyYOucmfHx8YzhaLOYa7cYJ34UVvWcYeoahjzy/HBa1YeD+kFZP2IwmMWINQf5OkYGbUwSd4qa71X1nt3HVeXqPK1PHHpCg1l+dHs84rlyszPVGWRpBrsLmNQ3KJA9lUoxn7lhysDlq+NmhxUKZvGwCGRHYYFxs8acRrd32rctWrQKZl4KfIQhdBfIGt32qSowLm6AZBHg0TpM4zuWt8pA9gTW8ZzN0nRZIQSX7p0RBGMjuAei4kC+rPTWCiVSZ+N7DEm/1LpqrobjktO6HNdaw/GNV+f2ZNCuAlEV4LkpMmrmLOmtpJlWpUArNAcki4O7UAZk3pTP+sCwVFfY3xLfAyC7HMsh7P3vGeBmGYWojgD5xOBhwpn4LV7FP7F9exBbTfzRxLN4kfjx7Zd4kfuDJv6Lrfgr15NKiUfpTp0D8vXak4YaA09lZ+3Lnj09871waEX3tU5wPUKPu5PuxJlTNZ",
	"MD": "271710719-E54F6D8F865285D4",
}

Response

Redirect Http code 200

Success https://epay.homebank.kz/payform/success.html Params amount currency invoiceID accountID description reference language cardid

Error https://epay.homebank.kz/payform/ invoiceID code message