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

Компанияның API арқылы жұмыс істеу үшін PCI DSS сертификаты болуы керек

Тіркеу кезінде сізге төлем жасаған кезде пайдалануыңыз қажет деректер беріледі:

TerminalIDДүкен сәйкестендіргіші
ClientIDКлиент сәйкестендіргіші
ClientSecretҚұпия кілт

Тестілік коммерсант

URLhttps://test-epay.homebank.kz/login
emailepay@halykbank.kz
passwordXZG1E@Mm
ClientIDtest
ClientSecretyF587AV9Ms94qN2QShFzVR3vFnWkhjbAK3sG
TerminalID40a348cb-68a3-45d5-9002-a4836d79c3b5

Тестілік карталар

PANExpire DateCVCStatus
440563970401509601/25815unlock
552204270506673601/25525unlock
37751450000482001/254169unlock
400303270454759709/20170lock
557834271075056009/20254lock

Аударым жасау үшін токенді алу

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Тапсырыстың сипаттамасы
merchantIdForSavingCardsCell
IdТапсырыс нөмірін коммерсант жасайды, әрбір жаңа тапсырыс үшін тапсырыс нөмірі бірегей, 6-дан 15 цифрға дейін болуы керек. Егер сіздің тапсырыс нөміріңізде 6-дан астам таңба болса, онда бірегейлік қосымша соңғы 6 таңба бойынша сақталуы керек
senderIPЖіберушінің IP-і (міндетті емес)
senderEmailКлиенттің email-ы (міндетті емес)
Foreignfalse
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
idcardid
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