Подать заявку

С вами кто-то свяжется в ближайшее время

Оставьте заявку на подключение

Ваша заявка принята в обработку. Вам ответят на электронную почту в рабочем порядке.

Спасибо за обращение

Создать сайт

Tilda — это один из конструкторов, с помощью которого можно собрать свой сайт из готовых блоков

Создайте сайт на <a>Tilda</a>

Подробнее

Придите в филиал АО «Народного банка Казахстана» и менеджер поможет Вам подписать договор

Подпишите <span>договор</span>

<span>Быстрый старт</span> вашего интернет - магазина, без навыков программирования

Мы подготовили для вас подробную инструкцию

Видеоинструкция

Когда сайт готов и договор подписан, необходимо подключить модуль к Вашему сайту

Подключите модуль <span>ePay</span>

# API
## Oauth

>> URL test https://testoauth.homebank.kz/epay2  
>> URL prod https://https://test-epay-oauth.epayment.kz

[Получение токена](https://developer.homebank.kz/epay/api/poluchenie-tokena)  
[Обновление токена](https://developer.homebank.kz/epay/api/obnovlenie-tokena)  
[Отзыв токена](https://developer.homebank.kz/epay/api/otzyv-tokena)  

## API

>> URL test https://testepay.homebank.kz/api

>> URL prod https://epay-api.homebank.kz

* [Отмена платежа](https://developer.homebank.kz/epay/api/cancel)  
* [Подтверждение/Частичное подтверждение](https://developer.homebank.kz/epay/api/podtverzhdenie-chastichnoe-podtverzhdenie-operacii)  
* [Возврат/Частичный возврат](https://developer.homebank.kz/epay/api/vozvrat-chastichnyi-vozvrat)

# Платеж через 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

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

# Описания работы сервиса P2P по 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
```

__Запрос__
Body: form-data

```
grant_type:     "client_credentials"
scope:          "transfer"
invoiceID:      "12321312312"
secret_hash: "JDKCNDDGGDTPSKJD"
amount:         "100"
currency        "KZT"
client_id:      "test"
client_secret:  "yF587AV9Ms94qN2QShFzVR3vFnWkhjbAK3sG"
terminal:       "40a348cb-68a3-45d5-9002-a4836d79c3b5"

```

| Поле     | Описание     |
| ---------- | ---------- |
| grant_type       | тип авторизации, для проведения платежа используется тип авторизации: client_credentials  |
| invoiceID     | Номер заказа, генерируется коммерсантом, должен быть уникальный для каждого нового заказа,от 6 до 15 цифр. Если ваш номер заказа содержит более 6 символов, то дополнительно уникальность должна соблюдаться по последним 6ти символам    |
|secret_hash  |  дополнительное секретное значение(строка), сгенерированное системой интернет-магазина, которое будет возвращено на Postlink |
| amount     | сумма     |
| currency     | валюта     |
| scope       | ресурс      |
| client_id       | Идентификатор коммерсанта, можно получить в кабинете, выдается при регистрации     |
| client_secret       | Ключ доступа коммерсанта, можно получить в кабинете, выдается при регистрации       |
| terminal     | Идентификатор точки продаж, можно получит в кабинете, выдается при регистрации      |

__Ответ__
 ```
    {
      "access_token":"DCEB8O_ZM5U7SO_T_U5EJQ",
      "expires_in": 7200,
      "refresh_token":"",
      "scope":"transfer",
      "token_type":"Bearer"
    }

  ```

| Поле    | Описание     |
| ---------- | ---------- |
| access_token      | Токен для проведения операции       |
| expires_in       | Время истечения токена      |
| refresh_token     | Не используется при данном типе авторизации    |
| scope       | Ресурс, для проведения платежа используется ресурс transfer    |
| token_type      | Тип авторизации     |

После получения токена, необходимо передавать его в __Headers Bearer DCEB8O_ZM5U7SO_T_U5EJQ__ 

на эндпоинт: 
```
TEST URL https://testepay.homebank.kz/api/p2p/transfer
PROD URL https://epay-api.homebank.kz/p2p/transfer
```

метод POST, в теле запроса в формате JSON указывать след структуру: 

Body: raw

```
{
  "order": {
    "amount": 100,
    "currency": "KZT",
    "description": "TEST p2p",
    "merchantIdForSavingCards": "",
    "id": "123456787538",
    "senderIP": "",
    "senderEmail": "armanali@epay.kz",
    "foreign": false,
    "terminalId": "40a348cb-68a3-45d5-9002-a4836d79c3b5",
    "backLink": "https://epay.homebank.kz/demo/success.html",
    "failureBackLink": "https://epay.homebank.kz/demo/failure.html",
    "postLink": "https://epay.homebank.kz/payform",
    "failurePostLink": "https://testmerchant/order/1123/fail"
  },
  "card": {
    "sender": {
      "save": false,
      "transferType": "TYPEPAN",
      "address": "",
      "cvc": "815",
      "cardCred": "4405639704015096",
      "expire": {
        "month": "01",
        "year": "25"
      },
      "name": "Sergey Frolov",
      "number": ""
    },
    "receiver": {
      "save": false,
      "id": "",
      "transferType": "TYPEPAN",
      "cardCred": "5522042705066736"

    }
  }
}

```

__Описание полей отправителя sender:__

| Поле     | Описание     |
| ---------- | ---------- |
| Amount       | Сумма заказа       |
| currency       | Валюта       |
| description       | Описание заказа       |
| merchantIdForSavingCards       | Cell       |
| Id       | Номер заказа, генерируется коммерсантом, должен быть уникальный для каждого нового заказа,от 6 до 15 цифр. Если ваш номер заказа содержит более 6 символов, то дополнительно уникальность должна соблюдаться по последним 6ти символам      |
| senderIP       | IP отправителя(не обязательно)     |
| senderEmail       | email клиента (не обязательно)      |
| Foreign       | false       |
| terminalId       | Идентификатор магазина       |
| backLink       | Ссылка для возврата в магазин при удачном платеже      |
| failureBackLink       | Ссылка для возврата в магазин при не удачном платеже      |
| postLink       | Уведомление о платеже      |
| failurePostLink       | Уведомление о неудачном платеже, если не заполнено, то информация будет отправлена на адрес указанный в postLink      |
| Save       | Сохранить карту – true, не сохранять - false      |
| transferType       | Тип проведения перевода, "TYPEPAN"  - по номеру карты, "TYPECARDID"  - по сохраненной карте epay|
| Address       | Адрес      |
| CVC       | CVV      |
| Id       | Передавать пустое значение     |
| Month       | Месяц      |
| Year       | Год      |
| Name       | Имя      |
| cardCred       | Номер карты отправителя/ id карты    |

__Описание полей получателя receiver__

| Поле     | Описание     |
| ---------- | ---------- |
| save       | Сохранить карту – true, не сохранять - false      |
| id       | Cardid       |
| cardCred       | Номер карты получателя      |
| firstName       | Имя - только для переводов за рубеж     |
| lastName       | Фамилия - только для переводов зарубеж       |
| countryCode       | Код страны - только для переводов зарубеж   |

__Ответ в случае успеха:__

```

{
    "id": "a9e1b986-be01-4763-9216-610cc63b963c",
    "amount": 200,
    "currency": "KZT",
    "email": "epay@halykbank.kz",
    "description": "TEST p2p",
    "reference": "204978430339",
    "orderID": "1234567893774576",
    "senderCardID": "88481433-595e-4c01-941f-34569db2426e",
    "senderCardPAN": "4003********9821",
    "receiverCardID": "86496cb0-bb5d-4791-bb49-cc27a0f660ce",
    "receiverCardPAN": "5578********0613",
    "intReference": "6BD1808D0FF129B0",
    "terminalID": "95555555",
    "code": 0,
    "status": "CHARGE"
}

```

__Ответ в случае неудачи:__

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

```

После получения результата по оплате с 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 https://epay-api.homebank.kz/p2p/api/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

Переводы по API

### Cсылка на оплату по API

__Документация для API-интерфейса создания счетов в системе электронных платежей ePay:__

**Получения токена:**

**Метод: POST**

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

**Body**: form-data

```
    grant_type:        "password"
    username:          "halykfinanceUSD@halykbank.nb"
    password:          "XVp36qar"
    scope:             "webapi usermanagement email_send verification statement statistics payment"
    client_id:         "halykfinanceUSD"
    client_secret:     "U01gQZVL##lJ$NhJ"
    secret_hash:       "JDKCNDDGGDTPSKJD"

```

**Response**

```
  {
    "access_token": "IRPNGDU-PBYMXBCXTC5AMG",
    "expires_in": "900",
    "refresh_token": "O8EGZOGOVVAQGUAADC_WBG",
    "scope": "webapi usermanagement email_send verification statement statistics payment",
    "token_type": "Bearer"}

```

**Authorization: Bearer DCEB8O_ZM5U7SO_T_U5EJQ**

**URL:**
**Метод: POST**

```
URL prod https://epay-api.homebank.kz/invoice
URL test https://testepay.homebank.kz/api/invoice
```

**Данные для тестирования:**

```
shop_id prod: e16cfde-f3e9-49c6-8cf9-2d3f080f739c
shop_id test: 04f25a4b-d2bd-4dd8-b3a7-9390be4774c4
```

**Входные параметры:**
**Метод: JSON**

```

{
    "shop_id": "04f25a4b-d2bd-4dd8-b3a7-9390be4774c4",
    "account_id": "0003413423",
    "invoice_id": "25458124232312321",
    "amount": 100,
    "language": "rus",
    "description": "asdasdasdas",
    "expire_period": "1d",
    "recipient_contact": "EXAMPLE@halykbank.kz",
    "recipient_contact_sms": "+777711111111",
    "notifier_contact_sms": "",
    "currency": "KZT",
    "post_link": "https//mail.ru",
    "failure_post_link": "https//mail.ru",
    "back_link":"https//mail.ru",
    "failure_back_link":"https//mail.ru"
}
```

**Поле**  | **Описание** |
------------- | ------------- |
**shop_id (строка)**| - ID магазина, выдается системой при регистрации магазина, обязательное|
**account_id (строка)**| - номер счета магазина в системе epay, генериурется коммерсантом, обязательное|
**invoice_id (строка)**| - уникальный идентификатор номера в системе магазина, генериурется коммерсантом, обазательное |
**amount (число)**| - сумма счета, обязательное|
**language (строка)**| - язык, на котором должна быть представлена информация о счете (допустимые значения: "rus", "kaz", "eng"), обязательное|
**description (строка)**| - описание счета, допустимое количество символов 125, обязательное|
**expire_period (строка)**| - период действия счета. Формат: "[число][единица времени]", где единица времени может принимать значение "d" (дни). Например, "2d" - счет действителен в течение двух дней, обязательное|
**recipient_contact (строка)**| - электронный адрес получателя счета, обязательное|
**recipient_contact_sms (строка)**|- номер мобильного телефона получателя счета в формате "+7XXXXXXXXXX", обязательное|
**notifier_contact_sms (строка, необязательный к заполнению)**| - номер мобильного телефона для отправки уведомлений об оплате в формате "+7XXXXXXXXXX".|
**currency (строка)**| - валюта счета (допустимые значения: "KZT"), обязательное|
**post_link (строка, необязательный)**| - URL-адрес, на который будет отправлен POST-запрос после успешной оплаты счета.|
**failure_post_link (строка, необязательный)**| - URL-адрес, на который будет отправлен POST-запрос в случае неуспешной оплаты счета.|
**back_link**| - Ссылка для возврата в магазин при удачном платеже.|
**failure_post_link**| - Ссылка для возврата в магазин при неудачном платеже.|

### Ответ:
```
{
    "id": "19c435ae-fbe6-4761-863f-381f6a0fe824",
    "shop_id": "4e16cfde-f3e9-49c6-8cf9-2d3f080f739c",
    "amount": 100,
    "invoice_id": "25458124232312321",
    "language": "rus",
    "currency": "KZT",
    "description": "test",
    "account_id": "0003413423",
    "recipient_contact": "EXAMPLE@halykbank.kz",
    "recipient_contact_sms": "+777711111111",
    "notifier_contact": "",
    "notifier_contact_sms": "+777711111111",
    "expire_period": "1d",
    "post_link": "",
    "failure_post_link": "",
    "created_date": "2023-03-28T10:04:10.997074088+06:00",
    "expire_date": "2023-03-30T10:04:10.997074088+06:00",
    "status": "ACTIVE",
    "updated_date": "0001-01-01T00:00:00Z",
    "invoice_url": " https://testepay.homebank.kz/api/redirect/invoice-link/19c435ae-fbe6-4761-863f-381f6a0fe824",
    "merchant_id": " ad638b1d-e515-4b9c-aab3-d3500735f6eb",
    "terminal_id": "d9d7978c-d6ee-4ec0-8cda-165251a4bf16"
}

```

**Поле**  | **Описание** |
------------- | ------------- |
**id (строка)**| Уникальный идентификатор счета в системе ePay.|
**shop_id (строка)**| Идентификатор магазина, зарегистрированного в системе ePay.|
**amount (число)**|Сумма счета.|
**invoice_id (строка)**| Уникальный идентификатор счета в системе магазина, от 6 до 15 цифр.|
**language (строка)**|Язык, на котором представлена информация о счете.|
**currency (строка)**| Валюта счета.|
**description (строка)**|Описание счета.|
**account_id (строка)**| Идентификатор счета магазина.|
**recipient_contact (строка)**| Электронный адрес получателя счета.|
**recipient_contact_sms (строка)**| Номер мобильного телефона|
**expire_period (строка)**| Период действия счета|
**post_link (строка)**|URL-адрес, на который будет отправлен POST-запрос после успешной оплаты счета.|
**failure_post_link (строка)**| URL-адрес, на который будет отправлен POST-запрос после успешной оплаты счета.|
**created_date**| Дата создания ссылки|
**expire_date**| Срок действия ссылки|
**status**| Статус ссылки на оплату.|
**invoice_url**| Ссылка на оплату|
**terminal_id (GUID)**| Номер виртуального терминала в системе ePay|

**Проверка статуса ссылки**
Сервис позволяет проверить статус сгенерированной ссылки

**Требуется авторизация**
**Метод: POST**

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

**Body**: form-data

```
    grant_type:        "password"
    username:          "halykfinanceUSD@halykbank.nb"
    password:          "XVp36qar"
    scope:             "api"
    client_id:         "halykfinanceUSD"
    client_secret:     "U01gQZVL##lJ$NhJ"
```
**Response**

```
{
    access_token": "IRPNGDU-PBYMXBCXTC5AMG",
    "expires_in": "900",
    "refresh_token": "O8EGZOGOVVAQGUAADC_WBG",
    "scope": "webapi usermanagement email_send verification statement statistics payment",
    "token_type": "Bearer"}

}
```
**Authorization: Bearer DCEB8O_ZM5U7SO_T_U5EJQ**

**URL:**
```
TEST URL POST https://testepay.homebank.kz/api/invoice-links
PROD URL POST https://epay-api.homebank.kz/invoice-links
```

**Метод: POST**

**Request**

```
{
    "paging": {
        "skip": 0,
        "limit": 20
    },
    "searchParameters": [
        {
            "name": "invoice_id",
            "method": "=",
            "searchParameter": [
                "200220241201"
            ]
        }
    ],
    "orderParameters": {
        "field": "id",
        "typeOrder": "DESC"
    }
}

```

В блок "paging" , необходимо передавать два параметра: 
- "skip" - количество записей которые необходимо пропустить; 
- "limit" - количество записей которые необходимо вывести на странице.

В блок "searchParameters", необходимо передавать три параметра, так же можно производить поиск по множеству полей (в примере запроса показано как):
- "name" - наименование поля(фильтра) по которому будет происходить поиск в БД, в нашем случае по номеру заказа invoice_id; 
- "method" - метод поиска (указывать в следующем виде : between, like , =) ; 
- "searchParameter" - параметры поиска.При использование метода поиска between необходимо передавать 2 параметра, при использование like, передавать один параметр который содержит знак %, при методе поиска in необходимо использовать минимум 1 параметр. В случае не корректно переданных параметров , будет возвращаться ошибка. В запросе необходимо указывать номер заказа. Данный параметр поиска является обязательным.

**Response**

```
{
    "TotalCount": 1,
    "Records": [
  {
            "id": "39400628-6ebd-4640-9a25-116fb847db37",
            "shop_id": "04f25a4b-d2bd-4dd8-b3a7-9390be4774c4",
            "amount": 400,
            "invoice_id": "200220241201",
            "language": "rus",
            "currency": "KZT",
            "description": "tes ",
            "account_id": "",
            "recipient_contact": "test@test.kz",
            "recipient_contact_sms": "+77778877887",
            "notifier_contact": "",
            "notifier_contact_sms": "+77778877887",
            "expire_period": "2d",
            "post_link": "https://epay.homebank.kz/payform",
            "failure_post_link": "https://testmerchant/order/1123/fail",
            "back_link": "",
            "failure_back_link": "",
            "created_date": "2024-02-20T15:15:29.289897+06:00",
            "expire_date": "2024-02-22T15:15:29.289897+06:00",
            "status": "CHARGED",
            "updated_date": "0001-01-01T05:07:48+05:07",
            "invoice_url": "https://testepay.homebank.kz/api/redirect/invoice-link/39400628-6ebd-4640-9a25-116fb847db37",
            "merchant_id": "ad638b1d-e515-4b9c-aab3-d3500735f6eb",
            "terminal_id": "d9d7978c-d6ee-4ec0-8cda-165251a4bf16",
            "card_save": false
        }
    ]
}

```

**Деактивация ссылки на оплату** 

Сервис позволяет деактивировать ссылку, чтобы клиент не мог по ней оплатить (при этом, если по ссылке прошел успешный платеж, повторно по ней не удастся, на нашей стороне имеется ограничение по связке номер терминала + инвойс)
То есть, если по ссылке прошел успешный платеж деактивировать ее нет необходимости. Деактивирование ссылки никак не влияет на уже прошедший платеж. 

Требуется авторизация

**Получение токена**
**Метод: POST**

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

**Body**: form-data
```
    grant_type:        "password"
    username:          "halykfinanceUSD@halykbank.nb"
    password:          "XVp36qar"
    scope:             "webapi usermanagement email_send verification statement statistics payment"
    client_id:         "halykfinanceUSD"
    client_secret:     "U01gQZVL##lJ$NhJ"

```
**Response**

```
{
  "access_token": "IRPNGDU-PBYMXBCXTC5AMG",
    "expires_in": "900",
    "refresh_token": "O8EGZOGOVVAQGUAADC_WBG",
    "scope": "webapi usermanagement email_send verification statement statistics payment",
    "token_type": "Bearer"}

```
Authorization: Bearer DCEB8O_ZM5U7SO_T_U5EJQ

__URL : https://testepay.homebank.kz/api/deactivate/invoice-links/:invoicelinkid__

__Метод: PUT__

__Invoicelinkid – уникальный идентификатор счета в системе ePay при ответе сгенерированной ссылки__


ссылка на оплату по АПИ

Cсылка на оплату по API

# Сервис для проверки действительности карты и при необходимости ее сохранения 

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

```
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: "halykfinanceUSD"
client_secret: "U01gQZVL##lJ$NhJ"
invoiceID: "Номер заказа"
amount: 0
currency: "USD"
terminal: "d9d7978c-d6ee-4ec0-8cda-165251a4bf16"

```

### Ответ

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

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

| Название поля | Описание | Обязательное/не обязательно |
| -------- | -------- | -------- |
| amount | Cумма платежа всегда 0 | Oбязательное |
| currency| Валюта всегда USD | 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 | Линк для отправки результата авторизации в магазин |  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":"0d4d345e-8566-43bd-b046-028b5aee6406"
}

```

Структура должна быть зашифрована при помощи публичного 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":0,
  "currency":"USD",
  "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,
  "paymentType": "cardVerification",
  "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",
  "accountID": "uuid000001",
  "amount": 0,
  "amountBonus": 0,
  "currency": "USD",
  "description": "test payment",
  "email": "jj@example.com",
  "invoiceID": "938290483290",
  "language": "RUS"
  "phone":"77777777777",
  "reference": "114537489258",
  "intReference": "435G34G34534T546",
  "secure3D": null,
  "cardID": "111DFSDF-3F43-18V4-V34-ASD12342323",
  "fee": 0,
  "code": 0,
  "status":"VERIFIED",
  "secureDetails": ""
  "qrReference": ""
}

```

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

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": 0,
    "amountBonus": 0,
    "currency": "USD",
    "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 https://epay-api.homebank.kz/payments/confirm?Access=:token

```

```
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",
}
```

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

```

HTTP/1.1 200 OK

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

Проверка/сохранение карты

# Apple Pay by API
**Для работы через API коммерсанту необходимо зарегистрироваться в системе apple и уметь расшифровывать данные, которые в последствии необходимо будет передавать в нашу систему**

**Интеграцию возможно проводить только в продуктовой среде**

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

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

```
PROD URL POST https://epay-oauth.homebank.kz/oauth2/token
```

### Запрос

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

### Ответ

```json
{
  "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| Bалюта |  Oбязательное  |
| name | Имя держателя карты |  Oбязательное  |
| сryptogram | Закриптованные параметры платежной карты |  Oбязательное  |
| invoiceId     | Номер заказа в магазине | Oбязательное  |
| invoiceIdAlt     | дополнительный номер заказа в магазине | Hеобязательно  |
| description | В данном поле передается информация о товарах или услугах, за которые производится оплата | 
| accountId | Идентификатор клиента в системе коммерсанта или другой доп. параметр на усмотрение коммерсанта |  Hеобязательно  |
| email  | Email клиента | Hеобязательное  |
| phone  | Tелефон клиента | Hеобязательно  |
| postLink | Линк для отправки результата авторизации в магазин |  Hеобязательное  |
| failurePostLink | Линк для отправки неудачного результата авторизации либо информации об ошибке в магазин |  Hеобязательно  |
| cardSave| Параметр сохранение карты, true - сохранить карту, false - не сохранять, boolean type |  Oбязательное  |

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

Структура криптограммы:
``` json
{
  hpan string
  expDate string
  cvc string
  terminalId string
}
```
Пример:
```
{
 "hpan":"AppleToken",
 "expDate":"expToken",
 "cvc":"",
 "terminalId":"67e34d63-102f-4bd1-898e-370781d0074d"
}

```

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

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

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

### Запрос

Заголовок запроса:
```
Content-Type: application/json
Authorization: Bearer DCEB8O_ZM5U7SO_T_U5EJQ
```

Тело запроса:
``` json
{
    "amount": 10.0,
    "currency": "KZT",
    "name": "Arman Ali",
    "cryptogramApplePay": "Расшифрованная криптограмма от Apple ",
    "cryptogram": "jkasDHJIHUIHDUIOHUI23HDUI2NUIBN2I23NDJIN2OIEN2IODN0I23J0M230IDJMI023MDKDMKLSFJSDF651454564SDFIOHF984N98HFIJ2HF"
    "invoiceId": "163637162556226",
    "invoiceIdAlt":"8564546",
    "description": "Оплата через applePay",
    "accountId": "",
    "email": "armanali@gmail.com",
    "phone": "+77771232380",
    "backLink": "http://example/backLink",
    "failureBackLink": "http://example/failureBackLink",
    "postLink": "http://example/postLink",
    "failurePostLink": "http://example/failurePostLink",
    "paymentType": "applePay"
}

```

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

``` json 
HTTP/1.1 200 OK

{
  "id":"7943816b-58a8-47f6-a11e-67b63c4228c7",
  "amount": 100,
  "currency":"KZT",
  "invoiceID":"938290483290",
  "invoiceIdAlt":"8564546",
  "accountID":"uuid000001",
  "phone":"77777777777",
  "email":"jj@example.com",
  "description":"test payment",
  "reference":"114537489258",
  "language":"rus"
}
```

### Результат по неуспешной оплате

``` json
HTTP/1.1 400 OK

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

```

## Результат операции по оплате с 3DSecure
```json
{  
    "id": "7943816b-58a8-47f6-a11e-67b63c4228c7",
    "accountId": "",
    "amount": 100,
    "amountBonus": 0,
    "currency": "KZT",
    "description": "Оплата заказа 938290483290",
    "email": "",
    "invoiceID": "938290483290",
    "invoiceIdAlt":"8564546",
    "language": "RU",
    "phone": "",
    "reference": "",
    "intReference": "",
    "secure3D": {
    "paReq": "eyJtZXNzYWdlVHlwZSI2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiIyMDFiZDlmYy1kM2IzLTQ4YjUtYWRiNy1jYjM1YT6IjA1In0",
        "md": "MjAxYmQ5ZmsadasdtY2IzNWE1NjFhM2Mw",
        "action": "https://epay-proxy.homebank.kz/"
    },
    "cardID": "",
    "fee": 0
}
```
После получения результата по оплате с 3DSecure необходимо переадресовать клиента на форму ввода пароля.

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

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

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

``` json 
<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: MjAxYmQ5ZmsadasdtY2IzNWE1NjFhM2Mw 
```

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

```
URL POST /payment/confirm
```

``` json
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": "MjAxYmQ5ZmsadasdtY2IzNWE1NjFhM2Mw",
}
```

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

Apple Pay через API

# Документация для отправки запроса на оплату с использованием Google Pay c зашифрованными данными(PAYMENT_GATEWAY):

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

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

```
### Запрос:
```json
grant_type: "client_credentials"
scope: "webapi usermanagement email_send verification statement statistics payment"
client_id: "ClientID"
client_secret: "clientSecret"
InvoiceID: "Order number"
amount: 100
currency: "KZT"
terminal: "67e34d63-102f-4bd1-898e-370781d0074d"
```

### Ответ:
```json
{
"access_token": "DCEB8O_ZM5U7SO_T_U5EJQ",
"expires_in": 7200,
"scope": "webapi usermanagement email_send verification statement statistics payment",
"token_type": "Bearer"
}
```
## Входящие параметры:
| Название поля | Oписание | Обязательное/не обязательно |
| -------- | -------- | -------- |
| amount | Cумма платежа | Обязательное |
| currency| Bалюта | Обязательное |
| name | Имя держателя карты | Обязательное |
| cryptogram | Закриптованные параметры платежной карты | Обязательное |
| invoiceID | Номер заказа, генерируется коммерсантом, должен быть уникальный для каждого нового заказа, от 6 до 15 цифр. Если ваш номер заказа содержит более 6 символов, то дополнительно уникальность должна соблюдаться по последним 6ти символам | Обязательное |
| invoiceIdAlt | Номер заказа, генерируется коммерсантом, должен быть уникальный для каждого нового заказа, от 6 до 15 цифр | Необязательно |
| description | В данном поле передается информация о товарах или услугах, за которые производится оплата | Обязательное |
| AccountId | Идентификатор клиента в системе коммерсанта или другой доп. параметр на усмотрение коммерсанта | необязательно |
| email | Еmail клиента | Необязательно |
| phone | Телефон клиента | Необязательно |
| postLink | Линк для отправки результата авторизации в магазин | Необязательно |
| failurePostLink | Линк для отправки неудачного результата авторизации либо информации об ошибке в магазин | Необязательно |
| cardSave| Параметр сохранение карты, true - сохранить карту, false - не сохранять, boolean type | Обязательное |
| data| Дополнительное поле транслируется в отчете при заполнении | Необязательно  |

# Проведение платежа
## URL: https://epay-api.homebank.kz/payment/cryptopay

## Method: POST
## Тело запроса:
## json

``` json
{
    "amount": 10,
    "currency": "KZT",
    "name": "Test test",
    "terminalId": "b861ab50-8387-46c3-be6e-f439d4492c3c",
    "invoiceId": "80000148",
    "description": "Оплата",
    "accountId": "",
    "email": "nemesis_311@gmail.com",
    "phone": "+77078071180",
    "backLink": "http://example/backLink",
    "failureBackLink": "http://example/failureBackLink",
    "postLink": "http://example/postLink",
    "failurePostLink": "http://example/failurePostLink",
    "cardSave": false,
    "useBonus": false,
    "paymentType": "googlePay",
    "googlePay": {
        "apiVersionMinor": 0,
        "apiVersion": 2,
        "paymentMethodData": {
            "description": "Visa •••• 1111",
            "tokenizationData": {
                "type": "PAYMENT_GATEWAY",
               "token": "{\"signature\":\"MEQCIG0Pt0VSb8/W00fzbPLtO5z3DYNrG1IrU94YI0U3VZw3AiAekJRW2Bcq1+hPbcbBniw9vRNSH2w3+qFX5EcQwkJo1w\\u003d\\u003d\",\"intermediateSigningKey\":{\"signedKey\":\"{\\\"keyValue\\\":\\\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEwIIrniC3/DfJjejVaHVsBGZLO9LW9ggLXWaoEVnpZuFgLSH4qEanNlHvZkr6A04aVq/7HgYaxLkotk6ZKSr3qQ\\\\u003d\\\\u003d\\\",\\\"keyExpiration\\\":\\\"1695271732552\\\"}\",\"signatures\":[\"MEQCIFurLZqmGGY9jZ+ZL+8iHtdxFRY3VMdKwcxrO0tunvuoAiBywEKS7Q2qwh4SmjY99tNaVYrfr8/Cygd8c/0XoP2K4Q\\u003d\\u003d\"]},\"protocolVersion\":\"ECv2\",\"signedMessage\":\"{\\\"encryptedMessage\\\":\\\"5XrIV3etzcSBdH8fgO+eCIxH3jWrGSUPPVXci3s22nD5Ab+9EtihPz/Zc3ODVwINNWOtkqfJxiu3UUaz1LbICfM1I2rhqyANCc35fK+Fd/JZNQv7eFNVVNxVdt2eBiQxPod+2K5v4jCJJkGevdbqQUW1OncL1QXpt8e/dNj1o7CTGCxxV6iN+8DjAo4xyvZJqKsjA3PzzKDhfNdM6zohKcgNqtPP30uI8EGK1PdGQDFCuPYFRYpKCVOx3qibRuI5x46pHV86GLUmMDbETSNOIYnwpOu0RVcMLdb74xQ9awoiXILSSM/IGhQUJnxeUbckzYsqwbZ88Ks6kmbHmCs3oHcgL4Lblt7hE07vW1Y1VJQ05/oTcT98R9WWzKeOTSvA8ru7o3oUxdwww1QIb9VytOz2IbGiI+ZepGehImTxsOUJkG3QwoFevDVDV67cf6KfTxUd97OarcE6Nk3crwO+GIASJw/U5lycj74HRd/h25Fme8TFf6BMmcOHUezy6Tx+iHO5j3P0QMDT0a4bVb8wuUPa0CE1DQH75E+EVSUb2tmRURkqDrDKCN6GP2VCvxqsSzV26zZbl8Xv\\\",\\\"ephemeralPublicKey\\\":\\\"BOmDg7vgShCeyoYT5EgzyV8NGdh3AbDe1yHmf2WRv+tKYlfjd8bhGJnc1hkLVjY80VKFBxUw2eDhqd1bGzXoxQ0\\\\u003d\\\",\\\"tag\\\":\\\"I9P/hCUvJTg+cVO7H+snaOAtACB9J0gySh/LEih0yH8\\\\u003d\\\"}\"}"
               },
            "type": "CARD",
            "info": {
                "cardNetwork": "VISA",
                "cardDetails": "1111"
            }
        }
    }
}

```

 ## Поля запроса:
| amount | Сумма платежа в валюте указанной в поле currency |
| -------- | -------- | 
| currency |Валюта платежа в формате ISO 4217 (например, "KZT" для казахстанского тенге) |
| name | Имя плательщика |
| terminalId | Идентификатор терминала или магазина для обработки платежа 
| invoiceId |Идентификатор счета или заказа, связанный с платежом |
| description | Описание платежа |
| accountId | Идентификатор аккаунта плательщика (если применимо) |
| email | Адрес электронной почты плательщика |
| phone | Телефонный номер плательщика |
| backLink | URL для перенаправления пользователя после успешного завершения платежа |
| FailureBacklink | URL для перенаправления пользователя в случае неудачного завершения платежа |
| postlink |URL, на который провайдер платежей отправит обратную связь о статусе платежа после успешного завершения |
| failurePostlink | URL, на который провайдер платежей отправит обратную связь о статусе платежа в случае неудачного завершения|
| cardSave | Флаг, указывающий, нужно ли сохранять данные карты плательщика для будущих платежей (в данном случае установлено значение false) |
| useBonus | Флаг, указывающий, нужно ли использовать бонусные средства плательщика для оплаты (в данном случае установлено значение false)|
| paymentType | Тип платежа, в данном случае установлено значение googlePay |
| googlePay | Объект, содержащий информацию о платеже с использованием Google Pay |
| apiVersionMinor | Версия API Google Pay (в данном случае установлено значение 0) |
| apiVersion | Версия API Google Pay (в данном случае установлено значение 2) |
| paymentMethodData | Объект, содержащий информацию об используемом способе оплаты |
| descrption | Описание способа оплаты (например,"Visa •••• 1111") |
| tokenizationData | Объект, содержащий информацию о токенизации платежных данных |
| type | Тип токенизации (в данном случае установлено значение PAYMENT_GATEWAY) |
| token | Значение токена полученное от системы Google |
| type | Тип способа оплаты (в данном случае установлено значение CARD) |
| info | Объект, содержащий информацию о платежной карте |
| cardNetwork | Сеть платежной карты (например, "VISA") |
| cardDetails | Последние четыре цифры номера платежной карты (например, "1111")  |

После отправки запроса на API оплаты, вы ожидаете получить ответ с информацией о статусе платежа. Обработайте ответ соответствующим образом в вашей системе используя сервис проверки статуса платежа

```
TEST URL: GET https://testepay.homebank.kz/api/check-status/payment/transaction/:invoiceid
```
```
PROD URL: GET https://epay-api.homebank.kz/check-status/payment/transaction/:invoiceid
```

## Требуется авторизации: client credentials
Запрос
Получение токена

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

```
## Body: form-data
``` json
grant_type: "client_credentials"
scope: "webapi usermanagement email_send verification statement statistics payment"
client_id: "test"
client_secret: "yF587AV9Ms94qN2QShFzVR3vFnWkhjbAK3sG"
terminal: "67e34d63-102f-4bd1-898e-370781d0074d"

```

| Поле | Описание | 
| -------- | -------- | 
| grant type | Тип авторизации, для проведения платежа используется тип client_credentials | 
| scope| Ресурс | 
| client id | Идентификатор коммерсанта, можно получить в кабинете, выдается при регистрации |
| client secret | Ключ доступа коммерсанта, можно получить в кабинете, выдается при регистрации |
| terminal | Идентификатор точки продаж, можно получит в кабинете, выдается при регистрации | 

### Ответ:
``` json
{
"access_token": "DCEB8O_ZM5U7SO_T_U5EJQ",
"expires_in": 7200,
"scope": "webapi usermanagement email_send verification statement statistics payment",
"token_type": "Bearer"
}
```

| Поле | Описание | 
| -------- | -------- | 
| access token | Токен для проведения операции | 
| expires in| Время истечения токена | 
| refresh token | Не используется при данном типе авторизации |
| scope | Ресурс, для проведения платежа используется ресурс |
| token type | Тип авторизации | 

``` json
Headers
    Authorization: Bearer dGVzdGNsaWVudDpzZWNyZXQ=

HTTP CODE 200

Responce Body JSON:

{
    "resultCode": "100",
    "resultMessage": "SUCCESS",
    "transaction": {
        "id": "af2089fe-43b1-47eb-a61f-c78dd196e18d",
        "createdDate": "2022-11-15T03:52:17.289853+06:00",
        "invoiceID": "205218074",
        "amount": 12.22,
        "amountBonus": 0,
        "payoutAmount": 10,
        "orgAmount": 22.22,
        "approvalCode": "170243",
        "data": "{\"custom_id\":\"2023.03.10-15:03:58\",\"email\":\"epay@halykbank.kz\",\"deal_number\":\"1111111\",\"offer_code\":\"1111111\",\"sum\":33900}",
        "currency": "KZT",
        "terminal": "98120001",
        "terminalID":"67e34d63-102f-4bd1-898e-370781d0074d",
        "accountID": "",
        "description": "order 205218074",
        "language": "RU",
        "cardMask": "400303...9821",
        "cardType": "VISA",
        "issuer": "Казкоммерцбанк",
        "reference": "231951411351",
        "reason": "Successfully",
        "reasonCode": "00",
        "intReference": "67140D7DE97139A7",
        "secure": false,
        "statusID": "5bbb7dd5-4691-41ee-a6a5-755a3d23a218",
        "statusName": "REFUND",
        "name": "ARMAN ALI",
        "email": "epay@halykbank.kz",
        "phone": "",
        "cardID": "e8a09f98-04b4-71a6-e053-1d1a000aa0d2",
        "xlsRRN": "",
        "ip": "46.148.239.182",
        "ipCountry": "Kazakhstan",
        "ipCity": "",
        "ipRegion": "",
        "ipDistrict": "",
        "ipLatitude": 55.7386,
        "ipLongitude": 37.6068
    }
}
```

### Error:
``` json
{
    "resultCode": "101",
    "resultMessage": "reject",
    "transaction": null
}
```

 ## resultcode
| Поле | Описание |  |
| -------- | -------- | -------- |
| 100 | Success | Успех выполнения запроса, в каком состоянии находиться платеж необходимо смотреть по statusName |
| 101 | Reject | Tранзакция неуспешная |
| 102 | Invoice not found, try again later or check transaction type (payment/p2p) | Hомер invoiceId не найден в системе, возможно ваша транзакция проходила по сервису p2p. |
| 103 | Try again or contact support | необходимо повторить запрос либо обратиться в службу поддержки |
| 104 | Field terminal absent in token | Oтсутствует параметр TerminalID при запросе токена |
| 106 | Error, incorrect terminalID | Hекорректный TerminalID при запросе токена |
| 107 | In progress | операция в процессе выполнения, запросите статус позже |

## statusName
| Поле | Описание |  
| -------- | -------- | 
| REFUND | Был осуществлён возврат списанной суммы | 
| AUTH | Сумма в блоке | 
| CANCEL | Сумма разблокирована |
| CHARGE | Сумма списана |
| CANCEL_OLD | Отмена авторизации на стороне Эмитента происходит в случае истечения срока действия операции CHARGE/CANCEL |
| FAILED | Транзакция неуспешная |
| 3D |  Ошибка на стадии проверки 3D| 
| NEW | Операция создалась но пока находится в промежуточном состоянии (если вы получили этот статус при запросе статуса транзакции вручную, то примите во внимание что он может быть изменён) |
| REJECT | Неуспешная попытка оплаты | 

### Вероятные reasonCode который вернет система размещены на ресурсе https://epayment.kz/docs/kody-oshibok

Google Pay Payment Gateway

# Google Pay by API
**Для работы через API коммерсанту необходимо зарегистрироваться в системе GOOGLE и уметь расшифровывать данные, которые, в последствии необходимо будет передавать в систему EPAY**
**Для работы по методу Pay by GOOGLE, компании необходимо наличие сертификации PCI DSS**

**Интеграцию возможно проводить только в продуктовой среде**

__ВНИМАНИЕ:__

__PAN_ONLY__: __Этот метод аутентификации связан с платежными картами, хранящимися в файле с учетной записью пользователя Google. Возвращаемые платежные данные включают номер личного счета (PAN) с указанием месяца и года истечения срока действия.__

__CRYPTOGRAM_3DS: Этот метод аутентификации связан с картами, хранящимися в виде токенов устройства Android. Возвращаемые платежные данные включают криптограмму 3D Secure (3DS), сгенерированную на устройстве__

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

## Данные для проведения тестовых платежей: 
|            |         | 
| ---------- | ---------- |
| url       | Hеобходимо использовать продуктовые данные   |
| email       | Hеобходимо использовать продуктовые данные     |
| password       | Hеобходимо использовать продуктовые данные       |
| ClientID       | Hеобходимо использовать продуктовые данные       |
| ClientSecret       | Hеобходимо использовать продуктовые данные       |
| TerminalID       | Hеобходимо использовать продуктовые данные       |

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

```
PROD URL POST https://epay-oauth.homebank.kz/oauth2/token
```

### Запрос:

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

### Ответ:

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

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

| Название поля | Oписание | Обязательное/не обязательно |
| -------- | -------- | -------- |
| amount | Cумма платежа | Oбязательное |
| currency| Bалюта | Oбязательное  |
| name | Имя держателя карты |  Oбязательное  |
| сryptogram | Закриптованные параметры платежной карты |  Oбязательное  |
| invoiceId     | Номер заказа в магазине | Обязательное  |
| description | В данном поле передается информация о товарах или услугах, за которые производится оплата | 
| accountId | Идентификатор клиента в системе коммерсанта или другой доп. параметр на усмотрение коммерсанта |  необязательно  |
| email  | Еmail клиента | Необязательное  |
| phone  | Телефон клиента | Необязательно  |
| postLink | Линк для отправки результата авторизации в магазин |  Необязательное  |
| failurePostLink | Линк для отправки неудачного результата авторизации либо информации об ошибке в магазин |  Необязательно  |
| cardSave| Параметр сохранение карты, true - сохранить карту, false - не сохранять, boolean type |  Обязательное  |

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

Структура криптограммы:
```JSON
{
  hpan string
  expDate string
  cvc string
  terminalId string
}
```
Пример:
```
{
 "hpan":"GOOGLEToken",
 "expDate":"mmyy",
 "cvc":"",
 "terminalId":"67e34d63-102f-4bd1-898e-370781d0074d"
}

```

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

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

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

### Запрос:

Заголовок запроса:
```
Content-Type: application/json
Authorization: Bearer DCEB8O_ZM5U7SO_T_U5EJQ
```

Тело запроса:
```js
{
    "amount": 10.0,
    "currency": "KZT",
    "name": "Arman Ali",
    "cryptogramGooglePay": "Расшифрованная криптограмм от Google",
    "сryptogram": "jkasDHJIHUIHDUIOHUI23HDUI2NUIBN2I23NDJIN2OIEN2IODN0I23J0M230IDJMI023MDKDMKLSFJSDF651454564SDFIOHF984N98HFIJ2HF"
    "invoiceId": "163637162556226",
    "invoiceIdAlt":"8564546",
    "description": "Оплата через Google",
    "accountId": "",
    "email": "ch.kabykenov@gmail.com",
    "phone": "+77778871188",
    "backLink": "http://example/backLink",
    "failureBackLink": "http://example/failureBackLink",
    "postLink": "http://example/postLink",
    "failurePostLink": "http://example/failurePostLink",
    "paymentType": "googlePay"
}

```

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

``` JSON
HTTP/1.1 200 OK

{
  "id": "7943816b-58a8-47f6-a11e-67b63c4228c7",
  "amount": 100,
  "currency": "KZT",
  "invoiceID": "938290483290",
  "invoiceIdAlt": "8564546",
  "accountID": "uuid000001",
  "phone": "77777777777",
  "email": "jj@example.com",
  "description": "test payment",
  "reference": "114537489258",
  "language": "rus"
}
```

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

``` JSON
HTTP/1.1 400 OK

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

```

Status Code 

> BUYER_ACCOUNT_ERROR. 
  Текущий пользователь Google не может предоставить платежную информацию.

> DEVELOPER_ERROR.
  Переданный параметр имеет неправильный формат. Сообщение об ошибке может появиться в консоли браузера для всех настроенных сред.

> MERCHANT_ACCOUNT_ERROR. 
  Сайт, обращающийся к Google Pay API, не имеет необходимого разрешения. Это может быть связано как с некорректной настройкой, так и с некорректным идентификатором мерчанта, указанным в запросе. Проверьте поле statusMessage для более подробной информации. Если у вас по-прежнему возникают проблемы, обратитесь в службу поддержки.

> INTERNAL_ERROR. Общая ошибка сервера.

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

```js
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 пароля.

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

```js
<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
```

```js
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

Google Pay через API

# **__Научитесь принимать платежи при помощи Google Pay™.__** 

---

## *Инструкция по подключению*

Данная инструкция предназначена для подключения возможности оплаты через Google Pay на своей странице оплаты при взаимодействии по API. При таком способе интеграции страница оплаты должна соответствовать определенным требованиям, в том числе работать через https и отвечать требованиям Google Pay™:

---

## *Принцип работы с сервисом*

Нажав на кнопку Google Pay, пользователь переходит на страницу, где указаны способы оплаты и адреса доставки, сохраненные в его аккаунте Google. 
Здесь пользователь может быстро выбрать способ оплаты.

Как происходит процесс оплаты:

1. 	Нажав кнопку Google Pay, пользователь переходит на страницу со списком доступных способов оплаты и выбирает нужный;
2. 	Google Pay безопасно передает токен, соответствующий указанному способу оплаты, на ваш сайт;
3. 	Ваш сайт отправляет своему серверу токен и другие детали платежа;
4. 	Сервер обрабатывает данные и передает токен поставщику платежных услуг.

---

## *Платёж через API*

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

При регистрации Вам будут выданы данные ниже, которые нужно будет использовать при проведении платежа:
-	MerchantID – идентификатор магазина
-	ClientID – идентификатор клиента
-	ClientSecret – секретный ключ

### __Получение токена для проведения оплаты__

    URL POST https://testoauth.homebank.kz/epay2/oauth2/token

### __Запрос__
```JSON
    grant_type: "client_credentials"
    scope: "payment"
    client_id: "ClientID"
    client_secret: "ClientSecret"
    invoiceID: "Номер заказа"
    amount: 100
    currency: "KZT"
    terminal: "MerchantID"
```
### __Ответ__
```JSON
    {
       "access_token":"DCEB8O_ZM5U7SO_T_U5EJQ",
       "expires_in": 7200,
       "scope": "payment",
       "token_type": "Bearer"
    }
```
### __Дополнительно прикладываем ссылки:__
    https://testepay.homebank.kz/api/payment/cryptopay -> Test URL
    https://epay-api-staging.homebank.kz/api/payment/cryptopay –> Staging URL
    https://epay-api.homebank.kz/api/payment/cryptopay -> Prod URL

### __Заголовок запроса__
    Content-Type: application/json
    Authorization: Bearer <code> DCEB8O_ZM5U7SO_T_U5EJQ </code>

### __Request JSON__
```JSON
{
    "amount": 100.0,
    "currency": "KZT",
    "name": "",
    "invoiceId": "",
    "description": "",
    "accountId": "",
    "email": "",
    "phone": "",
    "backLink": "",
    "failureBackLink": "l",
    "postLink": "",
    "failurePostLink": "",
    "language": "",
    "paymentType": "googlePay",
    "googlePay": {
"apiVersionMinor": 0,
"apiVersion": 2,
"paymentMethodData": {
    "description": "Visa •••• 1111",
    "tokenizationData": {
        "type": "DIRECT",
        "token": "{\"signature\":\"MEUCIQCg8EVRDoaFCClQt/B4P85kaI0o01Te7PtzK4geb020NgIgH/4QjV0g90wiSaIp5j2khIUehyBra5EBUYW4dRi9zWw\\u003d\",\"intermediateSigningKey\":{\"signedKey\":\"{\\\"keyValue\\\":\\\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEiPFGsUB3r5u94GfMb/qudvqnUm1ChMQJKb9DII454LnSflKA2CmwSCofunjyme+3YFEt58fQEhMCQTrfbJNSCA\\\\u003d\\\\u003d\\\",\\\"keyExpiration\\\":\\\"1650607298547\\\"}\",\"signatures\":[\"MEQCICLflkEi/5Gcf+yZVeoyqSgpobNYrTbfU8RYWooXoGMPAiAdeWeuPw5PMNCJynZN+2/AzHKEujn5x8DWb6nqwD0BdA\\u003d\\u003d\"]},\"protocolVersion\":\"ECv2\",\"signedMessage\":\"{\\\"encryptedMessage\\\":\\\"YDpsNtp8w1jnvnW1O6OBVjlX4p/cw+060kxrdHU3hOo5Dhq0UeO/2Pk6Y/lOpSq6xHgPQRM1BcalJU9QxKt6DjVm4mRx4CjZjiUu283ktfghFEmitR69HiTmvb1kRE1YAjcUpFadfoM9SsGC5YrJEe/5eRybwkn6IcSgJZZZ9CLqaw7qAjIZkZGbjNrSy9QdESDUdzcN5A7GMOWRMuQC/k9BmsBkvT7SLzikasPhLPP8z56J8E+m01nNBE5BCPhrLyu/aGoJNSdIJoRJoN88b//mS5b+TKsEIglGej8w54lpwpPr8GbqSPePHooN53QCkplY2t+LxO2Pr4jHEMb/ZaTQ36+58ZqUfV4jaYcds1SLuLMTns/3hnuTVZgg1zfBMQsNgZE5niAKPybL/RaRavRDX/GK4kVNjgsF1QWs8z2aOlBsx9krppHdthE\\\\u003d\\\",\\\"ephemeralPublicKey\\\":\\\"BP3QeTVZ6wpe3D83/OzF5A5FoNHDDnvBffeR8PAagr5PZP55SNR237a+QPyKUYmvKPYXe1R0I61GVK09LvkeGWE\\\\u003d\\\",\\\"tag\\\":\\\"Lq8NsPTu1rdHhthYFUtzptcV7aD7ViLVD8UddD8hNzY\\\\u003d\\\"}\"}"
    },
    "type": "CARD",
    "info": {
        "cardNetwork": "VISA",
        "cardDetails": "1111"
    }
}
    }
}
```
---

## *Действия продавца, необходимые для подключения Google Pay к вэб-странице*

Перед тем, как принимать платежи с помощью Google Pay, ознакомьтесь со всеми требованиями и условиями со стороны Google.

Подключение веб-страницы к Googel Pay API:
-	https://developers.google.com/pay/api/web/

Документация по подключению:
-	https://developers.google.com/pay/api/web/guides/tutorial

Рекомендации для подключения веб-страницы к Google Pay:
-	https://developers.google.com/pay/api/web/guides/brand-guidelines

Документация по разбору полезной нагрузки	
- https://developers.google.com/pay/api/web/guides/resources/payment-data-cryptography?hl=ru 

Набор тестовых карт

-	https://developers.google.com/pay/api/web/guides/resources/test-card-suite?hl=ru 

---

## *Действия продавца, необходимые для подключения Google Pay к приложению*

Перед тем, как принимать платежи с помощью Google Pay, обязательно ознакомьтесь со всеми требованиями и условиями со стороны Google.

Подключение Android приложения к Google Pay API:
- https://developers.google.com/pay/api/android/
Документация по подключению:
- https://developers.google.com/pay/api/android/guides/tutorial
Рекомендации для подключения Android приложения к Google Pay:
- https://developers.google.com/pay/api/android/guides/brand-guidelines

### Параметры для платёжных данных

В качестве параметров необходимо указать:

__Доступные методы платежа:__
    const allowedCardAuthMethods = ['PAN_ONLY', 'CRYPTOGRAM_3DS'];

__Тип токенизации__ - PAYMENT_GATEWAY

__Параметр gateway__
halykbank и gatewayMerchantId – можно использовать для Вашего тестирования, но для реальных платежей этот параметр должен быть получен у вашего менеджера:
```JSON
     const tokenizationSpecification = {
      type: "PAYMENT_GATEWAY",
      parameters: {
  'gateway': "halykbank",
  'gatewayMerchantId': "halykbank"
```
### Пример настройки запросов

__1. Параметры для запуска запроса:__ 
```JSON
isReadyToPay
const readyToPayRequest = {
    "apiVersion": 2,
    "apiVersionMinor": 0,
    "allowedPaymentMethods": [
{
    "type": "CARD",
    "parameters": {
        "allowedAuthMethods": [
            "PAN_ONLY",
            "CRYPTOGRAM_3DS"
        ],
        "allowedCardNetworks": [
            "MASTERCARD",
            "VISA"
        ]
    }
}
    ]
}
```

__2. Параметры для запуска запроса:__ 
```JSON
   loadPaymentData
const paymentDataRequest = {
    "apiVersion": 2,
    "apiVersionMinor": 0,
    "allowedPaymentMethods": [
{
    "type": "CARD",
    "parameters": {
        "allowedAuthMethods": [
            "PAN_ONLY",
            "CRYPTOGRAM_3DS"
        ],
        "allowedCardNetworks": [
            "MASTERCARD",
            "VISA"
        ]
    },
    "tokenizationSpecification": {
        "type": "PAYMENT_GATEWAY",
        "parameters": {
            "gateway": "halykbank",
            "gatewayMerchantId": "halykbank"
        }
    }
}
    ],
    "transactionInfo": {
"countryCode": "RU",
"currencyCode": "RUB",
"totalPriceStatus": "FINAL",
"totalPrice": "1.00"
    }
```
---

## *Сценарий оплаты*

1. Клиент выбирает способ оплаты Google Pay.
2. Клиент выбирает карту или добавляет ее если нет сохраненных карт.
3. Google Pay возвращает в приложение маскированные карточные данные.
4. Приложение отображает клиенту маскированные данные карты, добавленной в Google Pay.
5. Клиент подтверждает оплату с помощью добавленной в Google Pay карты.
6. Приложение запрашивает Google Pay зашифрованные карточные данные.
7. Google шифрует данные, используя открытый ключ - соответствующий ему закрытый ключ расположен в платёжном шлюзе. Открытый ключ формируем сами и отправляем в Google (https://developers.google.com/pay/api/web/guides/resources/payment-data-cryptography?hl=ru )
8. Google возвращает в приложение зашифрованные данные о платеже.
9. Приложение отправляет в платёжный шлюз запрос на оплату Google Pay, указывая полученный от системы Google Pay токен.
10. Платёжный шлюз расшифровывает полученный токен и производит оплату. 
11. При условии, что карта вовлечена в 3-D Secure, платёжный шлюз отправляет ответ на запрос на оплату, в котором содержится ссылка перенаправления на сервер где мы вводим данные по 3D.
12. Пользователь переходит на сайт и аутентифицируется.
13. После успешной аутентификации пользователя перенаправляют с сайта ACS на старницу платёжного шлюза.
14. Платёжный шлюз возвращает результат оплаты в приложение.
15. Приложение отображает результат оплаты клиенту.

---

Все продавцы должны соблюдать Политику использования API Google Play и принимать условия, определенные в Условиях предоставления услуг API Google Pay.
https://payments.developers.google.com/terms/aup
https://payments.developers.google.com/terms/sellertos