Submit an application

Someone will contact you soon

Leave a request for activation

Your application has been accepted for processing. You will receive an email reply in due course.

Thank you for contacting us

Create a website

Tilda - is one of the constructors with which you can build your website from ready—made blocks

Create a website on <a>Tilda</a>

More detailed

Come to the branch of Halyk Bank of Kazakhstan JSC and the manager will help you sign the contract

sign the <span>contract </span>

<span>Quick start</span> your online store, without programming skills

We have prepared detailed instructions for you

Video instruction

When the site is ready and the contract is signed, you need to connect the module to your site

Connect the module <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

## 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: "Номер заказа"
secret_hash: "JDKCNDDGGDTPSKJD"
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
}
```
Exаmple:
```
{
 "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 <https://epay-api.homebank.kz/public.rsa> <https://testepay.homebank.kz/api/public.rsa>
```
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,
  "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"
}
```
## 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"
secret_hash: "JDKCNDDGGDTPSKJD"
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 |
|  secret_hash  |  additional secret value(string) generated by the online store system which will be returned to Postlink |
| 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       | Еmpty       |
| 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       | Empty field     |
| 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": "CHARGE"
}

```

__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

### Link to API payment

__Documentation for the API for creating invoices in the ePay electronic payment system:__

```
**Getting a token:**

**Method: 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**

```json
{
    "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: Method: POST**
```
URL prod https://epay-api.homebank.kz/invoice
URL test https://testepay.homebank.kz/api/invoice
```

**Data for testing:**

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

__Input parameters:__
**Метод: JSON**

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

**Field**  | **Description** |
------------- | ------------- |
**shop_id (string)**| Store ID, issued by the system when registering the store, required|
**account_id (string)**| The account number of the store in the epay system, generated by the merchant, mandatory|
**invoice_id (string)**| Unique identifier of the number in the store's system, generated by the merchant, optional |
**amount (number)**| The amount of the invoice, required|
**language (string)**| The language in which the account information should be presented (acceptable values: "rus", "kaz", "eng"), required|
**description (string)**| Account description, 125 characters allowed, required|
**expire_period (string)**| Account validity period. Format: "[number][time unit]", where the time unit can take the value "d" (days). For example, the "2d" invoice is valid for two days, mandatory|
**recipient_contact (string)**| Email address of the account recipient, required|
**recipient_contact_sms (string)**|Mobile phone number of the account recipient in the format "+7XXXXXXXXXX", required|
**notifier_contact_sms (line, optional)**| Mobile phone number for sending payment notifications in the format "+7XXXXXXXXXX"|
**currency (line)**| Account currency (acceptable values: "KZT"), required|
**post_link (string, optional)**| The URL to which the POST request will be sent after successful payment of the invoice|
**failure_post_link (string, optional)**| The URL to which the POST request will be sent in case of unsuccessful payment of the invoice|

### Answer:
```json
{
    "id": "19c435ae-fbe6-4761-863f-381f6a0fe824",
    "shop_id": "4e16cfde-f3e9-49c6-8cf9-2d3f080f739c",
    "amount": 100,
    "invoice_id": "25458124232312321",
    "language": "rus",
    "currency": "KZT",
    "description": "asdasdasdas",
    "account_id": "0003413423",
    "recipient_contact": "EXAMPLE@halykbank.kz",
    "recipient_contact_sms": "+777711111111",
    "notifier_contact": "",
    "notifier_contact_sms": "+777711111111",
    "expire_period": "2d",
    "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"
}
```

**Field**  | **Description** |
------------- | ------------- |
**id (string)**| Unique identifier of the account in the ePay system|
**shop_id (string)**| The identifier of the store registered in the ePay system|
**amount (number)**|Invoice amount|
**invoice_id (string)**| Unique identifier of the invoice in the store's system, from 6 to 15 digits|
**language (string)**|The language in which the information about the invoice is presented|
**currency (string)**| Account currency|
**description (line)**| Account description|
**account_id (line)**| Store account ID|
**recipient_contact (line)**|Email address of the account recipient|
**recipient_contact_sms (line)**| Mobile phone number|
**expiry_period (string)**| Account validity period|
**terminal_id (GUID)**| The number of the virtual terminal in the ePay system|

**Checking the link status**
The service allows you to check the status of the generated link

**Authorization required**
**Method: 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 IRPNGDU-PBYMXBCXTC5AMG**

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

**Method: POST**

**Request**

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

```

Two parameters must be passed to the "paging" block: 
- "skip" - the number of records to be skipped; 
- "limit" - the number of records to be displayed on the page.

In the "searchParameters" block, three parameters must be passed, you can also search through a variety of fields (the query example shows how):
- "name" is the name of the field (filter) that will be searched in the database, in our case by the order number invoice_id; 
- "method" - the search method (specify in the following form : between, like , =);
- "searchParameter" - search parameters.When using the between search method, 2 parameters must be passed, when using like, pass one parameter that contains the % sign, with the in search method, at least 1 parameter must be used. If the parameters are not passed correctly, an error will be returned. The order number must be specified in the request. This search parameter is required.

**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
        }
    ]
}

```

**Deactivation of the payment link** 

The service allows you to deactivate the link so that the client cannot pay using it (at the same time, if a successful payment was made using the link, it will not be possible to re-use it, on our side there is a restriction on the combination of terminal number + invoice)
That is, if a successful payment was made via the link, there is no need to deactivate it. Deactivating the link does not affect an already completed payment in any way. 

Authorization is required.

__Getting a token__
**Method: 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__

_Method: PUT__

__Invoicelinkid is the unique identifier of the account in the ePay system when responding to the generated link__

invoice link API

Invoice link API

# A service for checking the validity of the card and, if necessary, saving it 

## Receiving a token for making a payment (for each operation, you must receive and use the original token)

```
PUBLISHING WITH A SIMPLE URL https://testoauth.homebank.kz/epay2/oauth2/token
PUBLISHING WITH A SIMPLE URL https://epay-oauth.homebank.kz/oauth2/token
```

### Request

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

```

### The answer

```
{
"access_token": "DCEB8O_ZM5U7SO_T_U5EJQ",
"expires_in": 7200,
"scope": "webapi usermanagement manages email intended for data transmission",
"token_type": "Representative".
}
```

## Incoming parameters

| Field name | Description | Required/Optional |
| -------- | -------- | -------- |
| amount | Amount that accounts for all time 0 | Required |
| currency| The currency of the whole world is USD | Required /
| name | I'm holding the cards | The designation /
| cryptogram | Encrypted parameters of the paid card | The designation |
| Invoice ID | The order number generated by the user can be unique for each new order, from 6 to 15 years old. If you want someone to say that you have more than 6 words, then you need more time to get together with those 6 words_________________________________ | Explanatory |
| Invoicing | Indicating the number generated by the user, maybe for each new order, from 6 to 15 years old | Required /
| description | In this case, information is provided about the product or services for which payment is made | Explanatory note|
| AccountId | User ID connected to the system computer, or a simple user interface for viewing data. | Automatic /
| Email | Client's email address | Desired |
| phone / Desired client | Desired /
| Mail link | Link to send for authorization in the store | Free of charge /
| failurePostLink | Link to opt out of a simple online authorization setup to send to the store | For free /
| cardsave| The parameter displays the map, true - displays the map, false - does not display, logical type | General |
| data| Fully distributed according to the request | Preferably |

## Preparing the cryptogram

Cryptogram structure:
```
{
hpan string
expDate string 
cvc string
terminalId string
}
```
Example:
```
{
"hpan": "4003032704547597",
"Accessed date": "1022",
"cvc": "636",
"User ID": "0d4d345e-8566-43bd-b046-028b5aee6406".
}

```

The structure should be focused on a potential user of the business class, who will find the right address
https://epay-api.homebank.kz/public.rsa
https://testepay.homebank.kz/api/public.rsa

## Making a payment

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

### Request

Request header:
```
Type used: application/json
Author: our representative is DCEB8O_ZM5U7SO_T_U5EJQ
```

Request body:
```
{
  "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"
}

```

## The result of a successful payment operation without 3D Secure

```

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

## The result of a failed payment transaction
```

HTTP/1.1 400 OK

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

```

## The result of the payment operation with 3D Secure

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

```

After receiving the result of the payment with 3D Secure, 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 Term Url parameter, you must use the address to which the merchant system will receive the result of the 3D Secure check. the password.

Example of building a form for redirecting a 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 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 3D Secure password verification)

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

## The result of a successful operation
```

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

Card Verification/Save

# 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

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

```
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
}
```
Еxample:
```
{
"hpan":"AppleToken",
"expDate":"DDMMYY",
"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:
``` json
{
"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

``` json
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": "rus"
}
```
### Result of unsuccessful payment

``` json
HTTP/1.1 400 OK

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

```

## Result of the payment transaction with 3DSecure
``` json
{
"id": "7943816b-58a8-47f6-a11e-67b63c4228c7",
"AccountId": "",
"amount": 100,
"accumtBonus": 0,
"currency": "KZT",
"description": "Order payment 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
}
```
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. the password.

Example of building a form for redirecting a 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>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: MjAxYmQ5ZmsadasdtY2IzNWE1NjFhM2Mw 
```

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

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

# Documentation on how to send a Google Pay payment request with encrypted data (PAYMENT_GATEWAY):

## Obtaining a token to make a payment (an original token must be obtained and used for each transaction) 

```
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: "Order number"
amount: 100
currency: "KZT"
terminal: "67e34d63-102f-4bd1-898e-370781d0074d"
```
### Response:
``` json
{
"access_token": "DCEB8O_ZM5U7SO_T_U5EJQ",
"expires_in": 7200,
"scope": "webapi usermanagement email_send verification statement statistics payment",
"token_type": "Bearer"
}
```

## Input parameters:

| Field name | Description | Required/optional |
| -------- | -------- | -------- |
| amount |Рayment amount | Required |
| currency| Currency | Required |
| name | Cardholder name | Required |
| cryptogram | Encrypted payment card parameters | Required |
| InvoiceID | The 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, then additionally the uniqueness should be observed for the last 6 characters | Required |
| invoiceIdAlt | The order number generated by the merchant must be unique for each new order, from 6 to 15 digits | Optional |
| description | This field contains information about the goods or services for which payment is made |Required |
| 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|
| data| Additional field is shown in the report false when filled | Optional |

# Payment processing
## URL: https://epay-api.homebank.kz/payment/cryptopay

## Method: POST
## Request body:

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

```
 ## Enquiry fields:

| Amount | Payment amount in the currency specified in the currency field |
| -------- | -------- |
| currency | Payment currency in ISO 4217 format (e.g. "KZT" for Kazakhstani tenge) |
| name | Name of the payer |
| terminalId | Identifier of the terminal or shop for payment processing |
| invoiceId | The identifier of the invoice or purchase order associated with the payment |
| description | Description of the payment |
| accountId | Payer’s account identifier |
| email | Payer’s email address |
| phone | Payer’s telephone number (if applicable) |
| backLink | URL to redirect the user to after successful payment |
| FailureBacklink | URL to redirect the user to if the payment is not successfully completed |
| postlink | URL to which the payment provider will send feedback on the payment status after successful completion |
| failurePostlink | URL to which the payment provider will send feedback on the payment status if the payment fails |
| cardSave | Flag indicating whether the payer's card details should be stored for future payments (set to false in this case) |
| useBonus | Flag indicating whether the payer's bonus funds should be used for payment (set to false in this case) |
| paymentType | Type of payment set to googlePay in this case) |
| googlePay | An object with information on the Google Pay payment |
| apiVersionMinor | API Google Pay version (set to 0 in this case) |
| apiVersion | Google Pay API version (set to 2 in this case) |
| paymentMethodData | An object with information on the payment method used |
| descrption | Description of the payment method (for example, “Visa •••• 1111”) |
| tokenizationData | An object with information about tokenization of payment data |
| type | Tokenization type (in this case it is set to PAYMENT_GATEWAY) |
| token | Token value received from Google |
| type | Type of payment method (in this case it is set to CARD) |
| info | An object with information about payment card |
| cardNetwork | Payment card network (for example, “VISA”) |
| cardDetails | The last four digits of the payment card number (for example, “1111”) |

After submitting a request to the payment API, you expect to receive a response with payment status information. Process the response accordingly in your system using the Payment Status Check service

```
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
```
## Authorisation required: client credentials
Request
Receiving token
```
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"

```

| Field name | Description | 
| -------- | -------- | 
| grant type | Type of authorization , client_credentials type is used to make a payment | 
| scope| Resource | 
| client id | The merchant identifier can be obtained in the personal account. It is issued during registration |
| client secret | Merchant access key can be obtained in the personal account. It is issued during registration |
| terminal id | The identifier of the point of sale can be obtained in the personal account. It is issued during registration | 

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

| Field name | Description | 
| -------- | -------- | 
| access token | Token for the transaction | 
| expires in| Token expiry time  | 
| refresh token | Not used for this type of authorization |
| scope | Resource. The resource is used to make the payment |
| token type | Type of authorization | 

``` json
Headers
    Authorization: Bearer dGVzdGNsaWVudDpzZWNyZXQ=

HTTP CODE 200

Response 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
| Field name | Description |  |
| -------- | -------- | -------- |
| 100 | Success | The success of the request execution. Payment status can be viewed using statusName |
| 101 | Reject | Unsuccessful transaction |
| 102 | Invoice not found, try again later or check transaction type (payment/p2p) | Your transaction may have been made using a P2P service if the invoiceId number is not found in the system |
| 103 | Try again or contact support | The request must be repeated or you should contact the Support Service |
| 104 | Field terminal absent in token | TerminalID parameter missing when a token is requested |
| 106 | Error, incorrect terminalID | Incorrect TerminalID when a token is requested |
| 107 | In progress | Transaction is in progress, please ask for status later |

## statusName
| Field name | Description |  
| -------- | -------- | 
| REFUND |The debited amount was refunded | 
| AUTH | Amount blocked  | 
| CANCEL | Amount unblocked |
| CHARGE | Amount debited |
| CANCEL_OLD | The Issuer cancels the authorization when  theCHARGE/CANCEL transaction expires. |
| FAILED | Unsuccessful transaction |
| 3D | Error at the 3D verification stage | 
| NEW | The transaction has been created but is still in an intermediate state (if you received this status when manually requesting the transaction status, please note that it may change) |
| REJECT | Unsuccessful payment attempt | 

### The probable reasonCode that will be returned by the system is available at https://epayment.kz/docs/kody-oshibok


Google Pay Payment Gateway

# 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**            | https://test-epay.homebank.kz|
| **email**          | epay@halykbank.kz         |
| **password**       | XZG1E@Mm                              |
| **ClientID**       | test                                  |
| **ClientSecret**   | yF587AV9Ms94qN2QShFzVR3vFnWkhjbAK3sG         |
| **TerminalID** | 67e34d63-102f-4bd1-898e-370781d0074d |

## 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:

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

### Response:

``` json
{
"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:
``` JSON
{
hpan string
expDate string
cvc string
terminalId string
}

Example:
{
"hpan":"GOOGLEToken",
"expDate":"mmyy",
"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:
```JSON 
{
"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

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

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

``` JSON
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
```JSON
    grant_type: "client_credentials"
    scope: "payment"
    client_id: "ClientID"
    client_secret: "ClientSecret"
    invoiceID: "Номер заказа"
    amount: 100
    currency: "KZT"
    terminal: "MerchantID"
```
### Response
```JSON
    {
       "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

```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:
```JSON
  const tokenizationSpecification = {
  type: "PAYMENT_GATEWAY",
  parameters: {
      'gateway': "halykbank",
  'gatewayMerchantId': "halykbank"
}
}
```
### Example of request settings

__1.Parameters for launching the request:__ 

```JSON
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:__ 
```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"
    }
}
```
    ---

## *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