Описания работы сервиса P2P по API

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

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


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

Тестовый коммерсант


URL	https://test-epay.homebank.kz/login
email	epay@halykbank.kz
password	XZG1E@Mm
ClientID	test
ClientSecret	yF587AV9Ms94qN2QShFzVR3vFnWkhjbAK3sG
TerminalID	40a348cb-68a3-45d5-9002-a4836d79c3b5

Тестовые карты

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

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

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

Запрос Body: form-data

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

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

Ответ

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

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

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

на эндпоинт:

TEST URL https://testepay.homebank.kz/api/p2p/transfer
PROD URL https://epay-api.homebank.kz/p2p/transfer

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

Body: raw

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

    }
  }
}

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

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

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

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

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


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

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

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

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

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

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

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

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

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

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

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

URL POST https://epay-api.homebank.kz/p2p/api/confirm

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

Response

Redirect Http code 200

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

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