Arendajale - tehniline info

 

​​​Test keskkond dubleerib reaalsete maksete töökeskonda. Alljärgnev kirjeldus kehtib, kui on avatud test-keskkonna konto.
Teil on vaja e-poe rakenduses realiseerida kaks suhtlusvoogu iPay serveri vastu.
1. Makse sooritamine, päring iPay serveri suunas. (algataja on Teie veebiteenus, vastuvõtja on "iPay server")
2. Makse vastuvõtu kinnitus, mida töödeldakse teie e-poe veebiteenuse poolt. (algataja "iPay server", vastuvõtja Teie e-poe veebiteenus)

​Makse sooritamine

​Teeme makse vastu https://pos.estcard.ee/test-pos/iPayServlet (iPay server) linki. Esmalt tuleb koostada http(s) protokollil põhinev ja soovitavalt POST meetodit kasutav päring. Päringu parameetrid on kirjeldatud alljärgnevas tabelis.

Tabel 1. Päringu parameetrid.
​Päringu parameetrid​Kirjeldus​Formaat​Näidisväärtus
lang ​​​suhtluskeel: ISO 639-1​​char (2)​ ​en
​action ​​maksevormi tunnus (gaf)​​​int (3)​ ​gaf
​ver ​​suhtlusprotokolli versioon (4)​int (3)​004
​id​​Teie unikaalne tunnus (ecom service-id)​​char (10)​​​318DC77DC8
​ecuno​unikaalne transatsiooninumber, mis seob
veebipoe poolt algatatud transaktsiooni
kaardimakse transaktsiooniga, formaat:
aeg formaadis [YYYYMM] + juhuslik
number piirkonnast 100000-999999
​​int (12) ​​201301822664
​​eamount​makse summa (sentides) ​​int (12)​ ​000000000019
​​cur​makse valuuta ISO-4217​char (3)​ ​EUR
​​datetime ​ajatempel: aeg formaadis
[YYYYMMDDhhmmss] ISO-8601
​​int (14)​ ​20130114134738
​charEncoding​​ ​kodeering UTF-8​​​char ​​UTF-8
FeedBackUrl​tagasiside link e-poe veebikeskonda​​char (128)http://www.wkiosk.com/pic/ecom/feedBack.php
delivery ​​tarne​meetodi kirjeldus ​​​char (1) 

​​S

additionalinfo​lisainfo väli kaupmehele (nt tellimuse nr vms) tarbeks​char (128)​pilet:12345;kaal:3kg​
mac ​​Signeeringu tulemus hex formaadis ​​hexdecimal ​350c16ae4016db9fac2f5c374f60a857lf56
fd4cf6f108e9f39d59b7c96e9f378a85c2d2
d8bf02b2cfe5e78a1b97984d405f359e1e28
49de3822430596a83b7a1dbe0f78f605e26d
8aae39f69e4dbd25387294e8bf611d323b32
8bc300bf7a188bfe8c9e04c67e56bade1e3ea19e

​​
*"mac" - sõnumi signatuur hexdecimal'is (edaspidi "hex"). iPay serveriga suhtlus protokoll on unikaalne. Koostada tuleb sõnum ("data"), mida kavatseme digitaalselt allkirjastada (signeerida). Selleks liidame väljad üheks pikaks stringiks.
Näidis andmete põhjal saame:
data = ver+id+ecuno+eamount+cur+datetime+feedBackUrl+delivery+additionalinfo
data = 004318DC77DC8201301822664000000000019EUR20130114134738http://www.wkiosk.com/pic/ecom/feedBack.php < - 128 - > S < - 128 - >pilet:12345;kaal:3kg​
 
Digitaalseks allkirjastamiseks (signeerimiseks) kasutame privaatset võtit. iPay serveri test keskkonna privaatse võtme saate alla laadida: mytestprivat.key
Tekkinud signeeringu räsi lisatakse "mac" parameetrina teiste päringu parameetritele lisaks. Vaata parameetreid tabel 1. Postituse vastuvõtjaks on siis iPay server.
 
* Digitaalse signeeringu hex viimise näide. Digitaalne signeeringu hex kujule viimise näide OPENSSL'iga. OPENSSL'i kasutatavaid krüpteerimise algoritme on implementeeritud peaaegu kõikides enamlevinud programeerimise keeltes. Teeme signeeringu ja viime ta hex kujule:
echo.-n 'data'  | openssl dgst -sha1 -sign mytestprivat.key - hex
Tulemuseks saame "mac"i (tabel 1 maci näidis väärtus). openssl'i käivitus parameetrite lühikirjeldus:
" dgst-sha1" - defineerime räsi SHA1 meetodil
"-sign mytestprivat.key " - signeerime privaatse võtmega mytestprivat.key
"-hex" - viime signeeringu binaarse tulemuse hex formaati.
 

Makse vastuvõtu kinnitus​

Saame makse kinnituse iPay serverilt "feedBackUrl"-le - feedBackUrl - vaata Tabel 1 feedBackUrl tulp näidise väärtus. 

Makse soorituse puhul iPay servlet saadab Teie veebiteenusele järgmised parameetrid (request).

Tabel 2. Request parameetrid
Päringu parameetrid​Kirjeldus​Formaat​Näidisväärtus (iPay)
ver​suhtlusprotokolli versioon​ int (3) ​004
​id​​Teie unikaalne tunnus maksesüsteemis
(ecom service-id)
​​char (10)318DC77DC8
ecuno ​​Teie veebikeskkonna poolt kaardimakse algatuse ajal genereeritud transaktsiooni number peegeldatuna tagasi iPay serveri poolt, selle abil saate siduda veebipoe tehingu kaardimakse tehinguga​ int (12)​​​201302734887
receipt_no​​Kaardimakse kviitungi number kaardimaksete keskkonnas ​​​int (6)​ ​00015
eamount ​​makse summa sentides ​​​int (12)​000000000019
cur ​​makse valuuta ISO-4217​​​char (3)​EUR
respcode ​​vastuskood kaardimakse keskkonnas ('000'=OK)​int (3) ​000
datetime ​ajatempel: formaat [YYYYMMDDhhmmss] ISO-8601​​​int (14)​20130208130525
msgdata ​​makse selgitus, kaardiomaniku nimi, vms., mida kaardiomanik ise sisestas maksevormile (NB! selle välja sisu kaardimaksete keskkonnas ei valideerita)​​​char (40)​nipitiri
actiontext ​​​(respcode) vastuskoodi selgituse sõnadega ​​​char (40)​ OK, approved
mac​iPay serveri sõnum hex formaadis (selle väärtuse õigsust peab kontrollima e-poe veebiteenuse)​-​​2D76944D9A057684609602DB7F
DE0872D4DEDD5B109FE9E4246E
475D8BDD13C438E93C6CA4FBC
9FBB1F6A96FB515B0C48F5387C
C25956A86BF9B02DFCE6C91E5C
913925D9DBC8A340E43FBAD5C9
5FDBF304A0E10BD56837DFBC9B
55F01DBCBB777D2DE96EEFEFAD
C014419B35E20C201CF721D4FD
4EF9FF895037F0466E661B


Algatuseks tuleb Teie veebiteenuse poolt koostada andmeblokk [data]. Selleks kasutame iPay serveri postitusest teie e-poe veebiteenusele saadetud andmeid. Liidame parameetrid üheks pikaks stringiks, kasutades tabelis toodud formaate.
 
data = ver+id+ecuno+receipt_no+eamount+cur+respcode+datetime+msgdata+actiontext
data = [004318DC77DC820130273488700015000000000019EUR00020130208130525nipitiri                      OK, approved                               ]
 
Nüüd kontrollime signeeringut. Selleks on vaja Test keskkonnas avalikku võtit, mille saate alla laadida SIIT:
ecomtestpublic.key
 
echo -n '$mac' | xxd -r -p >  /tmp/data.txt.sigh; echo -n '$data'
                         | openssl dgst -sha1 -verify ecomtestpublic.key -signature /tmp/data.txt.sign
 
Ootame openssl kontrolli tulemus: Verified OK
 
* "Feedback". "Feedback"i implementatsioon on Teie ja Teie klientide turvalisuse huvides.
Näide: kui keegi saadaks Teile "feedback" urlile järele tehtud parameetritega päringu ja Teie selle õigsust krüptograafiliselt ei kontrolliks, siis võite lihtsameelselt saata kauba või teenuse kliendile, kes on muutnud tagasisides olevate väljade väärtusi. Nets Estonia kontrollib alati "feedback" lingi toimivust lahenduse algsel kasutuselevõtmisel. Reaalset makseteenust teile ei avata, kui e-poes tagaside sõnumi kontrollimine ei toimi. Kui Teie makseteenus on avalikkusele avatud ja "feedback" teenus mingil põhjusel ei toimi, siis makseteenus peatatakse Nets Estonia poolt.
 
*Avaliku ja privaatse võtme genereerimine. Toodangu keskkonnas on vajalik iga müügikoha jaoks unikaalne kaupmehekohane privaatne võti ja sellega seotud kaupmehe avalik võti. See genereeritakse kaupmehe poolt näiteks käsureaga:
openssl genrsa -out myprivate.key 1024
 
Avaliku võtme saame käsureaga:
openssl rsa -in myprivate.key -pubout >mypublic.key
 
Kui võtmed on genereeritud, siis tekkinud "mypublic.key" tuleb saata Nets Estonia'sse (webpos@estcard.ee). Me registreerime Teie avaliku võtme iPay serveris.
 
*Avaliku ja privaatse võtme kontroll.
echo -n "0123456789abcdef" > data.txt ; openssl dgst -sha1 -sign myprivate.key -out data.txt.sign data.txt
                                                       |openssl dgst -sha1 -verify mypublic.key -signature data.txt.sign data.txt
NB! Ärge kunagi andke privaatset võtit kolmandate isikute kätte! Nagu kaotatud päris võtmetega, võib ka digitaalsete võtmetega avada neid teenuseid ja uksi, mida te ehk ei sooviks.
 
Nets Estonia toetab avatud lähtekoodi põhimõtteid. Kui Teil on mõni programeerimiskeele spetsiifiline näide ja soovite seda teistega jagada, siis saatke see näidis meile webpos@estcard.ee e-mailile. Lubame, et teeme sellise lähtekoodi kättesaadavaks kõigile.
 

*Programeerimise näited.

OPENSSL näide kasutades php'd ja "shell_exec" käsku.
makse - testPos.php.txt
tagasiside - feedBack.php.txt
 
PHP käsustik.
makse - testPos.php.txt
tagasiside - feedBackPHP.php.txt
refaktooritud kood -  refaktooritudPHP.txt

Java käsustik.
makse ja tagasiside - PaymentServlet.java.txt
 
*Peale edukalt läbituid teste.

Palume saata vastavasisuline e-mail webpos@estcard.ee selleks, et saada juhiseid edasiseks tegevuseks.