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

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

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

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

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

Создать сайт

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

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

Подробнее

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

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

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

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

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

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

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

# API

## Oauth

> > URL https://testoauth.homebank.kz/epay2

[Receive token](https://epayment.kz/ru/docs/poluchenie-tokena)  
[Update token](https://epayment.kz/ru/docs/obnovlenie-tokena)  
[Cancel token](https://epayment.kz/ru/docs/otzyv-tokena)

## API

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

- [Cancel payment](https://developer.homebank.kz/epay/api/cancel)
- [Confirm/Partially confirm payment](https://developer.homebank.kz/epay/api/podtverzhdenie-chastichnoe-podtverzhdenie-operacii)
- [Return/ Partially return payment](https://developer.homebank.kz/epay/api/vozvrat-chastichnyi-vozvrat)


# API based payments
**To work through the company's API, PCI DSS certification is required.**

Upon registration, you will be provided with data that will need to be used when making a payment:

- TerminalID - store identifier
- ClientID - client identifier
- ClientSecret - secret key

## Data for test payments: 
|            |         | 
| ---------- | ---------- |
| url       | https://test-epay.homebank.kz   |
| email       | epay@halykbank.kz     |
| password       | XZG1E@Mm       |
| ClientID       | test       |
| ClientSecret       | yF587AV9Ms94qN2QShFzVR3vFnWkhjbAK3sG     |
| TerminalID       | 67e34d63-102f-4bd1-898e-370781d0074d       |

### Test payment card

| PAN                  | Expire Date   | CVC  | Status |
| -------------------- | ------------- | ---- | ------ |
| 4405639704015096     | 01/25         | 815  | unlock |
| 5522042705066736     | 01/25         | 525  | unlock |
| 377514500004820      | 01/25         | 4169 | lock |
| 4003032704547597     | 09/20         | 170  | lock   |
| 5578342710750560     | 09/20         | 254  | lock   |

## Receiving  a token for payment (an original token must be obtained and used for each operation)

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

### Request

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

```

### Response

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

## Input parameters

| Field | Description | Required/Optional |
| -------- | -------- | -------- |
| amount | Payment amount | Required |
| currency| Currency |  Required  |
| name | Cardholder name |  Required  |
| сryptogram | Encrypted payment card parameters |  Required  |
| invoiceId     | Order number generated by the merchant, must be unique for each new order, from 6 to 15 digits. If your order number contains more than 6 characters, uniqueness must also be maintained for the last 6 characters | Required  |
| description | This field contains information about the goods or services for which the payment is being made | Required |
| accountId | Customer identifier in the merchant system or another additional parameter at the discretion of the merchant |  Optional  |
| email  | Customer email | Optional  |
| phone  | Customer phone | Optional  |
| postLink | Link for sending the authorization result to the store |  Required |
| failurePostLink | Link to send unsuccessful authorization results or error information to the store. |  Optional  |
|  cardsave| Card saving parameter, true - save the card, false - do not save, boolean type |  Required  |
|  data| Additional field transmitted in the report when filling out |  Optional|

## Preparing a cryptogram

Cryptogram structure:
```
{
  hpan string
  expDate string
  cvc string
  terminalId string
}

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

```

The structure must be encrypted using the public RSA key, which is available at
```
PROD URL https://epay-api.homebank.kz/public.rsa
TEST URL https://testepay.homebank.kz/api/public.rsa
```

## Payment Processing

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

### Request

Request Header:
```
Content-Type: application/json
Authorization: Bearer DCEB8O_ZM5U7SO_T_U5EJQ
```

Request Body:
```
{
  "amount":100,
  "currency":"KZT",
  "name":"JOHN JONSON",
"сryptogram":"UhYXAhYGeFA6srEVJ2V8Jtnnz6NzRwy8QDkCvEmJOcC6KyBP/Ce4SUM0A0My1zS1Iiur6AF0ajJwdi31EvrkRDBvzl2iLVKzvuAyusc5KuGpgxRhc6WXDhKkHV7J5Oew8uPMOfVbmXZ+Ypihos5ynSX7TnqQg1ImAmEISBxT+YU7jY68uxGhlehYMJ0lgS1Req4Z0BwCExBL2lwo05lmSMed69bEdBX552ue13zXjvTKIMrVj70hXIppXnxAE7haJfObuQzx2Ox+wM087kFPXfDX8Udlc6iRP2TxnRj7R1GnCTLvf3xlVU9ELzK+j91SPBQTvyEeyEvGMunjRch8lGXlogQreFSZmC5FUpfdfw6jYhl6lizUZYZzroN6/i5MILtV0US8zPFZTfozrCj8cvqw+J2W7yBywDiFoZG1teLDMIKIqTvkrmRL++Ji0psdHXl0z0ng/d0yTxzcBpPZ5V8VfNOexJJRZQUXBQqygAqqYninku/ls1NuTRMPeveyrgSMjQUVKU2W1izXdSreSdvaOio+1HJHNCZDwNn9yheTzbmuUsl5lhnsUGNT5gzMuYje8VfRYpsvG3Syz6nOijprG1wL3L/p5B/SZGrtaMMg/OdbD3mUWCSmat/V2v9RKHaeo5OHMnaVMTY5Tsqwa5JKBRP4ztRcjkjMRCBvS8c=",    
  "invoiceId":"000001",
  "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"
}

```

## Payment Result without 3DSecure

```

HTTP/1.1 200 OK

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

HTTP/1.1 400 OK

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

```

## Payment operation result with 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",
    "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": ""

```

After receiving the payment result with 3DSecure, the client needs to be redirected to the password input form.

To do this, the received parameters paReq, md, action are used.

In the TermUrl parameter, the address on which the merchant system will receive the 3DSecure password verification result needs to be used.

Example of building a form for redirecting the client:

```
<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();
}

```
The result of 3DSecure verification obtained at the merchant's 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 
```

Payment confirmation (sending the result of the 3DSecure password check)

```
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 based payments

# P2P BY API
__PCI DSS certification is required to work with the company via API__

Upon registration, you will be provided with data that will need to be used when making transfers:

|            |            |
| ---------- | ---------- |
| TerminalID       | Store identifier |
| ClientID       | Client identifier |
| ClientSecret       | Secret key |

__Test merchant__
|            |            |
| ---------- | ---------- |
| URL        | https://test-epay.homebank.kz/login |
| email      | epay@halykbank.kz |
| password   | XZG1E@Mm       |
| ClientID   | test       |
| ClientSecret      | yF587AV9Ms94qN2QShFzVR3vFnWkhjbAK3sG     |
| TerminalID    | 3ad0f5bd-88a8-464c-a9a4-cdb16d1dd31 |

### Test cards

| PAN                  | Expire Date   | CVC  | Status |
| -------------------- | ------------- | ---- | ------ |
| 4405639704015096     | 01/25         | 815  | unlock |
| 5522042705066736     | 01/25         | 525  | unlock |
| 377514500004820      | 01/25         | 4169 | unlock |
| 4003032704547597     | 09/20         | 170  | lock   |
| 5578342710750560     | 09/20         | 254  | lock   |

__Receiving a token for implementation a transfer__
```
TEST URL POST https://testoauth.homebank.kz/epay2/oauth2/token
PROD URL POST https://epay-oauth.homebank.kz/oauth2/token
```

__Request__
Body: form-data

```
grant_type:     "client_credentials"
scope:          "transfer"
invoiceID:      "12321312312"
amount:         "100"
currency        "KZT"
client_id:      "test"
client_secret:  "yF587AV9Ms94qN2QShFzVR3vFnWkhjbAK3sG"
terminal:       "c36b282f-6819-4d4f-85df-a4bdc8a8f703"

```

| Поле     | Описание     |
| ---------- | ---------- |
| grant_type       | Authorization type, for conducting a payment, the authorization type used is: client_credentials  |
| invoiceID     | Order number generated by the merchant, must be unique for each new order, from 6 to 15 digits. If your order number contains more than 6 characters, uniqueness must also be maintained for the last 6 characters. |
| amount     | Amount     |
| currency     | Currency     |
| scope       | Resource      |
| client_id       | Merchant ID, can be receiving in the merchant's account, issued upon registration     |
| client_secret       | Client identifier, issued upon registration       |
| terminal     | Store identifier, issued upon registration     |

__Response__
 ```
    {
      "access_token":"DCEB8O_ZM5U7SO_T_U5EJQ",
      "expires_in": 7200,
      "refresh_token":"",
      "scope":"transfer",
      "token_type":"Bearer"
    }

  ```

| Поле    | Описание     |
| ---------- | ---------- |
| access_token      | Token for implementation the operation      |
| expires_in       | Token expiration time    |
| refresh_token     | Not used for this type of authorization    |
| scope       | Resource, for conducting a payment, the resource used is transfer|
| token_type      | Authorization type    |

After receiving the token, it must be passed in 

__Headers Bearer DCEB8O_ZM5U7SO_T_U5EJQ__ 

to the endpoint: 
```
TEST URL https://testepay.homebank.kz/api/p2p/transfer
PROD URL https://epay-api.homebank.kz/p2p/transfer
```

__POST method, in the JSON format, should specify the following structure:__

Body: raw

```
{
  "order": {
    "amount": 100,
    "currency": "KZT",
    "description": "TEST p2p",
    "merchantIdForSavingCards": "",
    "id": "123456787538",
    "senderIP": "",
    "senderEmail": "armanali@epay.kz",
    "foreign": false,
    "terminalId": "c36b282f-6819-4d4f-85df-a4bdc8a8f703",
    "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": "951",
      "cardCred": "4003039802969821",
      "expire": {
        "month": "09",
        "year": "23"
      },
      "name": "Sergey Frolov",
      "number": ""
    },
    "receiver": {
      "save": false,
      "id": "",
      "transferType": "TYPEPAN",
      "cardCred": "5578342728230613",

    }
  }
}

```

__Sender fields description:__

| Field     | Description     |
| ---------- | ---------- |
| Amount       | Order amount       |
| currency       | Currency       |
| description       | Order description      |
| merchantIdForSavingCards       | empty       |
| Id       | Order number generated by the merchant, must be unique for each new order, from 6 to 15 digits. If your order number contains more than 6 characters, uniqueness should also be maintained for the last 6 characters     |
| senderIP       | Sender IP (optional)     |
| senderEmail       | Client email (optional)      |
| Foreign       | false       |
| terminalId       | Store identifier      |
| backLink       | Link to return to the store on successful payment      |
| failureBackLink       | Link to return to the store on unsuccessful payment      |
| postLink       | Link Payment notification |
| failurePostLink       | 	Notification of unsuccessful payment, if not filled in, the information will be sent to the address specified in postLink      |
| Save       | Save the card - true, don't save - false     |
| transferType       | Type of transfer, "TYPEPAN" - by card number, "TYPECARDID" - by saved epay card|
| Address       | Address      |
| Cvc       | cvv      |
| Id       | id- don't use     |
| Month       | month      |
| Year       | year      |
| Name       | Name      |
| cardCred       | Sender's card number/ card ID    |

__Receiver fields description:__

| Field     | Description     |
| ---------- | ---------- |
| save       | Save the card - true, don't save - false     |
| id       | cardid       |
| cardCred       | Receiver's card number  |
| firstName       | First name - only for international transfers     |
| lastName       | Last name - only for international transfers       |
| countryCode       | Country code - only for international transfers   |

__Success response:__

```

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

```

__Failure response:__

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

```

```

After receiving the payment result with 3DSecure, the client needs to be redirected to the password input form.

To do this, the received parameters paReq, md, action are used.

In the TermUrl parameter, the address on which the merchant system will receive the 3DSecure password verification result needs to be used.

Example of building a form for redirecting the client:

```
<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();
}

```
The result of 3DSecure verification obtained at the merchant's 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 
```

Payment confirmation (sending the result of the 3DSecure password check)

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

P2P API

P2P BY API

invoice link API

# Apple Pay using the API
**To work through the API, the merchant needs to register in the Apple system and be able to decrypt data that will later need to be transmitted to our system**

**Integration can only be carried out in a production environment**

- TerminalID – store ID
- Customer ID – Customer ID
- Client secret – Secret key

## Data for test payments: 
|            |         | 
| ---------- | ---------- |
| url | https://test-epay.homebank.kz |
| email | epay@halykbank.kz |
| password | XZG1E@Mm |
| Client ID | Test |
| clientSecret | yF587AV9Ms94qN2QShFzVR3vFnWkhjbAK3sG |
| Terminal ID | 67e34d63-102f-4bd1-898e-370781d0074d |

## Getting a token for making a payment (for each operation, you need to receive and use the original token)

```
A MESSAGE WITH A PROD URL https://epay-oauth.homebank.kz/oauth2/token
``

### Request

``
grant_type: "client_credentials"
scope: "webapi usermanagement email_send statement verification payment statistics"
client_id: "Client ID"
client_secret: "Client secret"
Invoice ID: "Order number"
amount: 100
currency: "KZT"
terminal: "67e34d63-102f-4bd1-898e-370781d0074d"
``

### Response

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

## Incoming parameters

| Field name | Description | Required/optional |
| -------- | -------- | -------- |
| amount | payment amount | required |
| currency| currency | required |
| name | cardholder name | required |
| cryptogram | encrypted payment card parameters | required |
| InvoiceID | Order number in the store | required |
| description | This field contains information about the goods or services for which payment is made | 
| Account ID | Customer ID in the merchant's system or other additional parameter at the merchant's discretion | optional |
| email | customer email | optional |
| phone | customer's phone | optional |
| Link to the publication | Link to send the authorization result to the store. | optional |
| failurePostLink | Link for sending an unsuccessful authorization result or error information to the store. | optional |
| cardSave| parameter saving the card, true - save the card, false - do not save, logical type | required |

## Cryptogram preparation

Cryptogram structure:
``
{
hpan string
  ExpDate string
cvc string
terminalId string
}

example:
{
"hpan":"AppleToken","ExpDate":"expToken","cvc":"","terminalId":"67e34d63-102f-4bd1-898e-370781d0074d"
}

```

The structure must be encrypted using a public and RSA key, which is available at
https://epay-api.homebank.kz/public.rsa

## Making a payment

``
URL OF THE PUBLICATION https://epay-api.homebank.kz/payment/cryptopay
``

### Request

Request header:
``
Content type: application/json
Authorization: Bearer DCEB8O_ZM5U7SO_T_U5EJQ
``

Request body:
``
{
"amount": 10.0,
"currency": "KZT",
"name": "Arman Ali",
"cryptogramApplePay": "Decrypted cryptogram from Apple",
"cryptogram": "jkasDHJIHUIHDUIOHUI23HDUI2NUIBN2I23NDJIN2OIEN2IODN0I23J0M230IDJMI023MDKDMKLSFJSDF651454564SDFIOHF984N98HFIJ2HF "
"InvoiceID": "163637162556226",
    "description": "Payment via ApplePay",
"Account ID": "",
"email": "armanali@gmail.com ",
"phone": "+77771232380",
"Backlink": "http://example/backLink ",
"failureBackLink": "http://example/failureBackLink ",
"postLink": "http://example/postLink ",
"failurePostLink": "http://example/failurePostLink ",
"PaymentType": "ApplePay"
}

```

### Result of payment operation without 3DSecure

```
HTTP/1.1 200 OK

{
"id": "7943816b-58a8-47f6-a11e-67b63c4228c7",
"amount": 100,
"currency": "KZT",
"InvoiceID": "938290483290",
"AccountId": "uuid000001",
  "phone": "77777777777",
"email":"jj@example.com ",
"description":"test payment",
"link":"114537489258",
"language": "Russian"
}
``

Apple Pay by API

# Google Pay by API
**To work through the API, the merchant needs to register in the GOOGLE system and be able to decrypt the data that will later need to be transmitted to the EPAY system**
**To work using the Pay by GOOGLE method, the company needs PCI DSS certification**

**Integration is possible only in the product environment**

__ATTENTION:__

__PAN_ONLY__: __This authentication method is associated with payment cards stored on file with the user's Google Account. Returned payment data includes personal account number (PAN) with the expiration month and the expiration year__

__CRYPTOGRAM_3DS: This authentication method is associated with cards stored as Android device tokens. Returned payment data includes a 3-D Secure (3DS) cryptogram generated on the device__

- TerminalID – store ID
- ClientID – client ID
- clientSecret – secret key

## Data for test payments:
| | |
| ---------- | ---------- |
| url | must use product data |
| email | it is necessary to use product data |
| password | must use product data |
| ClientID | need to use product data |
| clientSecret | it is necessary to use product data |
| TerminalID | product data must be used |

## Getting a token for making a payment (for each operation, you need to receive and use the original token)

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

### Request:

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

### Response:

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

## Incoming parameters:

| Field name | Description | Required/optional |
| -------- | -------- | -------- |
| amount | payment amount | required |
| currency| currency | required |
| name | cardholder name | required |
| cryptogram | encrypted payment card parameters | required |
| InvoiceID | Order number in the store | required |
| description | This field contains information about the goods or services for which payment is made |
| AccountId | Customer ID in the merchant's system or other additional parameter at the merchant's discretion | optional |
| email | client's email | optional |
| phone | client's phone | optional |
| postLink | Link for sending the authorization result to the store. | optional |
| failurePostLink | Link for sending an unsuccessful authorization result or error information to the store. | optional |
| cardSave| parameter saving the card, true - save the card, false - do not save, boolean type | required |

## Cryptogram preparation:

Cryptogram structure:
``
{
hpan string
expDate string
cvc string
terminalId string
}

example:
{
"hpan":"GOOGLEToken","expDate":"expToken","cvc":"","terminalId":"67e34d63-102f-4bd1-898e-370781d0074d"
}

```

The structure must be encrypted using a public RSA key, which is available at
https://epay-api.homebank.kz/public.rsa

## Making a payment:

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

### Request:

Request header:
``
Content-Type: application/json
Authorization: Bearer DCEB8O_ZM5U7SO_T_U5EJQ
```

Request body:
``js
{
"amount": 10.0,
"currency": "KZT",
"name": "Arman Ali",
"cryptogramGooglePay": "Decrypted cryptograms from Google",
"cryptogram": "jkasDHJIHUIHDUIOHUI23HDUI2NUIBN2I23NDJIN2OIEN2IODN0I23J0M230IDJMI023MDKDMKLSFJSDF651454564SDFIOHF984N98HFIJ2HF "
"InvoiceID": "163637162556226",
"description": "Payment via 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"
}

```

### Result of payment operation without 3DSecure

```
HTTP/1.1 200 OK

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

### Result of unsuccessful payment operation

```
HTTP/1.1 400 OK

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

```

Status Code

> BUYER_ACCOUNT_ERROR
The current Google user cannot provide payment information.

> DEVELOPER_ERROR
The passed parameter has an incorrect format. An error message may appear in the browser console for all configured environments.

> MERCHANT_ACCOUNT_ERROR
A site accessing the Google Pay API does not have the necessary permission. This may be due to both an incorrect setup and an incorrect merchant ID specified in the request. Check the statusMessage field for more details. If you still have problems, please contact support.

> INTERNAL_ERROR General server error.

## Result of payment operation with 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",
"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": ""

```

After receiving the result of the payment with 3DSecure, it is necessary to redirect the client to the password entry form.

To do this, the received parameters are used: PAReq, md, action.

In the TermUrl parameter, you must use the address to which the merchant's system will receive the result of the 3DSecure check. password.

Example of building a form for redirecting a client:

```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>Wait for the answer! <br><br>
Zhauabyn kutiniz!<br><br>
Wait for an answer!<br><br>
</h1>
</div>
</body>
<SCRIPT>function OnLoadEvent () {
document.forms[0].submit();
}

```
The result of the 3DSecure check received on the merchant's 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
```

Payment confirmation (sending the result of 3DSecure password verification)

```
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 by API

# **__Learn how to accept payments using Google pay™.__** 

---

## *Connection instructions*

This instruction is intended to enable the possibility of payment via Google Pay on your payment page when interacting via the API. 
With this integration method, the payment page must meet certain requirements, including working via https and meeting the requirements of Google Pay™:

---

## *The principle of working with the service*

By clicking on the Google Pay button, the user goes to the page where the payment methods saved in his Google account are indicated. 
This way he will be able to quickly choose the method of payment convenient for him.

Payment process:

1.	 By clicking the Google Pay button, the user goes to a page with a list of available payment methods and selects the desired one.
2.	Google Pay securely transfers the token corresponding to the specified payment method to your site.
3.	Your site sends its server a token and other payment details.
4.	The server processes the data and transfers the token to the payment service provider.

---

## *Payment via API*

*__To work through the API, the company needs PCI DSS certification.__*

During registration, you will be given the data that you will need to use when making a payment:
- MerchantID – store ID
- ClientID – client ID
- ClientSecret – secret key

### __Getting a token for making a payment__

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

### __Request__
    grant_type: "client_credentials"
    scope: "payment"
    client_id: "ClientID"
    client_secret: "ClientSecret"
    invoiceID: "Номер заказа"
    amount: 100
    currency: "KZT"
    terminal: "MerchantID"

### __Response__
    {
       "access_token":"DCEB8O_ZM5U7SO_T_U5EJQ",
       "expires_in": 7200,
       "scope":"payment",
       "token_type":"Bearer"
    }

### __Additionally we attach links:__
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

### __Request header__

    Content-Type: application/json
    Authorization: Bearer <code>DCEB8O_ZM5U7SO_T_U5EJQ</code>

### __Request 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"
    }
}
    }
}

---

## *Seller's actions required to connect Google Pay to a web page*

Before accepting payments using Google Pay, be sure to read all the requirements and conditions from Google.

Connecting a web page to the Google Pay API:
•	https://developers.google.com/pay/api/web/

Connection documentation:
•	https://developers.google.com/pay/api/web/guides/tutorial

Recommendations for connecting a web page to Google Play:
•	https://developers.google.com/pay/api/web/guides/brand-guidelines

Payload Parsing documentation
• https://developers.google.com/pay/api/web/guides/resources/payment-data-cryptography?hl=ru 

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

---

## *Seller's actions required to connect Google Play to the app*

Before accepting payments using Google Pay, be sure to read all the requirements and conditions from Google.

Connecting an Android app to the Google Pay API:
•	https://developers.google.com/pay/api/android/

Connection documentation:
•	https://developers.google.com/pay/api/android/guides/tutorial

Recommendations for connecting an Android app to Google Play::
•	https://developers.google.com/pay/api/android/guides/brand-guidelines

### Parameters for payment data

As parameters, you must specify:

__Available payment methods:__
    const allowedCardAuthMethods = ['PAN_ONLY', 'CRYPTOGRAM_3DS'];

__Type of tokenization__ - PAYMENT_GATEWAY

__Gateway parameter__
halykbank and gatewayMerchantId – can be used for your testing, but for real payments this parameter must be obtained from your manager:

  const tokenizationSpecification = {
  type: "PAYMENT_GATEWAY",
  parameters: {
      'gateway': "halykbank",
  'gatewayMerchantId': "halykbank"

### Example of request settings

__1.Parameters for launching the request:__ 

isReadyToPay
const readyToPayRequest = {
    "apiVersion": 2,
    "apiVersionMinor": 0,
    "allowedPaymentMethods": [
{
    "type": "CARD",
    "parameters": {
        "allowedAuthMethods": [
            "PAN_ONLY",
            "CRYPTOGRAM_3DS"
        ],
        "allowedCardNetworks": [
            "MASTERCARD",
            "VISA"
        ]
    }
}
    ]
}

__2. Parameters for launching the request:__ 

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

    ---

## *Payment scenario*

1. The customer chooses the Google Pay payment method.
2. The client selects a card or adds it if there are no saved cards.
3. Google Pay returns masked card data to the application.
4. The application displays the masked data of the card added to Google Pay to the client.
5. The customer confirms the payment using the card added to Google Pay.
6. The application requests Google Pay encrypted card data.
7. Google encrypts data using a public key - the corresponding private key is located in the payment gateway. We generate the public key ourselves and send it to Google (https://developers.google.com/pay/api/web/guides/resources/payment-data-cryptography?hl=ru )
8. Google returns encrypted payment data to the application.
9. The application sends a Google Pay payment request to the payment gateway, indicating the token received from the Google Pay system.
10. The payment gateway decrypts the received token and makes the payment. Provided that the card is involved in 3-D Secure, the payment gateway sends a response to the payment request, which contains a redirect link to the server where we enter 3D data.
11. The user goes to the site and authenticates.
12. After successful authentication, the user is redirected from the ACS website to the payment gateway page.
13. The payment gateway returns the payment result to the application.
14. The application displays the payment result to the client

---

All merchants must adhere to the Google Pay APIs Acceptable Use Policy and accept the terms defined in the Google Pay API Terms of Service.
https://payments.developers.google.com/terms/aup
https://payments.developers.google.com/terms/sellertos