Apple Pay by API

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

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

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

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

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

Запрос

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

Ответ

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

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

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

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

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

{
  hpan string
  expDate string
  cvc string
  terminalId string
}

Пример:

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

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

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

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

Запрос

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

Content-Type: application/json
Authorization: Bearer DCEB8O_ZM5U7SO_T_U5EJQ

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

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

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

HTTP/1.1 200 OK
{
    "id": "3a5f3d27-153e-4e8b-8643-a175b4f430e5",
    "accountId": "uuid000001",
    "amount": 300,
    "amountBonus": 0,
    "currency": "KZT",
    "description": "test payment",
    "email": "jj@example.com",
    "invoiceID": "8161284658531009",
    "language": "rus",
    "phone": "77777777777",
    "reference": "515456405139",
    "intReference": "430CB5FDCF84E4F1",
    "secure3D": null,
    "cardID": "2cc4d16b-8474-d20c-e063-1d1a000a5516",
    "fee": 0,
    "approvalCode": "622310",
    "code": 0,
    "status": "AUTH",
    "secureDetails": "",
    "qrReference": "",
    "ip": "172.30.212.238",
    "ipCity": "",
    "ipCountry": "",
    "ipDistrict": "",
    "ipLatitude": 0,
    "ipLongitude": 0,
    "ipRegion": "",
    "issuerBankCountry": "KAZ",
    "isCredit": false
}

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

HTTP/1.1 400 OK

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

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

{  
    "id": "7943816b-58a8-47f6-a11e-67b63c4228c7",
    "accountId": "",
    "amount": 100,
    "amountBonus": 0,
    "currency": "KZT",
    "description": "Оплата заказа 938290483290",
    "email": "",
    "invoiceID": "938290483290",
    "invoiceIdAlt":"8564546",
    "language": "RU",
    "phone": "",
    "reference": "",
    "intReference": "",
    "secure3D": {
    "paReq": "eyJtZXNzYWdlVHlwZSI2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiIyMDFiZDlmYy1kM2IzLTQ4YjUtYWRiNy1jYjM1YT6IjA1In0",
        "md": "MjAxYmQ5ZmsadasdtY2IzNWE1NjFhM2Mw",
        "action": "https://epay-proxy.homebank.kz/"
    },
    "cardID": "",
    "fee": 0
}

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

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

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

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

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

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

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

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

URL POST /payment/confirm

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