API бойынша P2P сервисі жұмысының сипаттамалары

Компанияның 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"
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 таңба бойынша сақталуы керек
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	сvv
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"
}

3D Secure арқылы төлеу бойынша нәтижені алғаннан кейін клиентті құпиясөзді енгізу нысанына бағыттау қажет.

Ол үшін мынадай алынған параметрлер қолданылады: paReq, md, action.

TermUrl параметрінде мерчант жүйесі 3D Secure құпиясөзді тексеру нәтижесін алатын мекенжайды пайдалану қажет.

Клиентті қайта бағыттау үшін нысанды құру мысалы:

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

Мерчанттың TermUrl-ға алынатын 3DSecure тексеру нәтижесі:

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

Төлемді растау (3D Secure құпиясөзін тексеру нәтижесін жіберу)

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