2011. 07.04. SSL Alapú Kártyatranzakciók az Interneten A CIB Bank Zrt. Internetes kártyaelfogadás szolgáltatás technikai dokumentációja Verziószám: 1.45 A CIB Bank internet technológián alapuló elektronikus kereskedelmi megoldásának dokumentációja. A jelen dokumentációban leírt módszerek és megoldások a CIB szolgáltatásának alapját képezik. A jelen leírás elfogadása esetén a dokumentumban leírt módszerektől eltérni semmilyen formában nem lehet. A CIB az SSL alapú kártyaelfogadás keretein belül a dokumentumban leírtaktól eltérő módszerekkel nem vállalja tranzakciók lebonyolítását.
TARTALOM 1. A RENDSZER RÖVID ELMÉLETI ÁTTEKINTÉSE... 4 1.1 Csomag tartalma:... 4 1.2 Fogalmak... 4 1.3 A fizetési folyamat... 5 2. PROBLÉMAKEZELÉS... 9 3. AZ ÁRUHÁZ ÉS A BANK KÖZÖTTI PROTOKOLL...10 3.1 Az egyes mezők definíciója... 10 3.1.1 Jelölések:... 10 3.1.2 Az adatmezők rövid összefoglalása... 10 3.1.3 Titkosítás típusa (CRYPTO)... 11 3.1.4 Üzenettípus (MSGT)... 11 3.1.5 ÁRUHÁZ azonosító (PID)... 11 3.1.6 Tranzakció azonosító (TRID)... 11 3.1.7 Ügyfél azonosító (UID)... 11 3.1.8 Összeg (AMO)... 12 3.1.9 Valutakód (CUR)... 12 3.1.10 Időpecsét (TS)... 12 3.1.11 Válaszkód (RC)... 13 3.1.12 Válasz szöveg (RT)... 13 3.1.13 Engedélyszám (ANUM)... 13 3.1.14 Authorizáció típusa (AUTH)... 13 3.1.15 URL (URL)... 13 3.1.16 Nyelvkód (LANG)... 13 3.1.17 Történet (HISTORY)... 14 3.1.18 Státusz (STATUS)... 14 3.2 Az egyes üzenetek struktúrája... 14 3.2.1 (2. lépés) Fizetési tranzakció inicializálása (ÁRUHÁZ BANK, MSGT=10)... 14 3.2.2 (3. lépés) Válasz fizetési tranzakció inicializálására (BANK ÁRUHÁZ, MSGT=11)... 15 3.2.3 (4-5. lépés) Vásárló fizetésre a BANK-ba irányítva (ÁRUHÁZ BANK, MSGT=20)... 15 3.2.4 (8-9. lépés) Vásárló fizetés után az ÁRUHÁZ-ba irányítva (BANK ÁRUHÁZ, MSGT=21)... 15 3.2.5 (10. lépés) Authorizáció eredményének lekérdezése, tranzakciós folyamat lezárása (ÁRUHÁZ- BANK, MSGT=32)... 15 3.2.6 (11. lépés) Authorizáció eredménye (BANK ÁRUHÁZ, MSGT=31)... 16 3.2.7 Authorizációs információkérés (ÁRUHÁZ BANK, MSGT=33)... 16 3.2.8 Tranzakció lépéseinek lekérdezése - Történet (ÁRUHÁZ BANK, MSGT=37)... 16 3.2.9 Válasz a tranzakció lépéseinek lekérdezésére (BANK ÁRUHÁZ, MSGT=38)... 17 3.2.10 A Tranzakcó adatainak/állapotának lekérdezése (ÁRUHÁZ-BANK, MSGT=70)... 17 Válasz a lekérdezésre (BANK ÁRUHÁZ, MSGT=71)... 17 3.2.11 Még nem terhelt tranzakciók visszavonása (ÁRUHÁZ-BANK, MSGT=74)... 18 Válasz a lekérdezésre (BANK ÁRUHÁZ, MSGT=75)... 18 3.2.12 Terhelés (banki zárás) után, tétel visszautalása tranzakció beállított összegével (ÁRUHÁZ- BANK, MSGT=78)... 18 Válasz a lekérdezésre (BANK ÁRUHÁZ, MSGT=79)... 18 3.2.13 Terhelés (banki zárás) után, visszautalandó összeg beállítása (ÁRUHÁZ-BANK,MSGT=80) 19 Válasz a lekérdezésre (BANK ÁRUHÁZ, MSGT=81)... 19 3.3 A [32] üzenet típusról bővebben... 19 3.4 A BANK szerverének válaszai... 20 3.5. Üzenettípusban definiálatlan hibakódok... 20 4. A CIB BANK FIZETÉSI FOLYAMATÁNAK RÉSZLETES LEÍRÁSA...22 4.1 Tesztkulcs, titkosító modul, titkos kulcs eljuttatása az ÁRUHÁZ fejlesztőjének... 22 4.2 Első lépés: tranzakció inicializálása... 22 4.3 Második lépés: az összeállított üzenet titkosítása... 24 2. oldal
4.3.1 SAKIDE programmal történő kódolás... 24 4.3.2 PHP nyelven (>PHP4) történő titkosítási kódrészlet:... 26 4.3.3 JAVA nyelven történő titkosítási kódrészlet:... 29 4.3.4 Fizetőoldali lépések folyamata... 33 4.3.5 Time-out miatti reverzálási folyamat leírása:... 34 4.4 Forinttól és eurótól eltérő devizanemben feltüntetett árakról... 35 4.5 Élesítés feltételei... 36 4.5.1 Logók megjelenítése... 36 4.5.2 ÁRUHÁZ működésre vonatkozó követelményei... 37 4.6 Élesítési kérés... 39 4.7 Élesítés... 40 5. VISSZAUTALÁS FOLYAMATA...41 5.1 Visszautalás lépései:... 41 6. A CIB TITKOSÍTÓ MODULJA...45 6.1 Az ekicrypt feladata és használatának feltételei... 45 6.2 Titkosítás specifikációja (ekiencodeurl)... 45 4.1 Visszafejtés az ekicrypt-el (ekidecodeurl)... 46 4.2 Kulcs struktúra (TKeyInfo)... 47 4.3 Kulcsinformációk lekérdezése (ekigetkeyinfo)... 47 4.4 Verziószám lekérdezése (ekigetlibversion)... 47 5. HIBALEHETŐSÉGEK, JAVASLATOK...48 8. VÁLTOZÁSKÖVETÉS...50 9. ELÉRHETŐSÉGEK...51 1. SZ. MELLÉKLET...52 2. SZ. MELLÉKLET...54 3. SZ. MELLÉKLET...56 3. oldal
1. A RENDSZER RÖVID ELMÉLETI ÁTTEKINTÉSE 1.1 Csomag tartalma: Technika specifikáció: Jelen dokumentum a CIB Bank Zrt. ecommerce szolgáltatásának használatát és a szolgáltatáshoz történő kapcsolódás lehetőségeit írja le. A fejlesztés során, valamint az esetlegesen a későbbiekben jelentkező hibajavítások során is hasznos információkkal szolgál. Titkosító program (ekicrypt.zip): tartalmazza a titkosító modul több platformra előfordított változatait, de megtalálható benne a.c forrás file is. A program szabvány 3DES algoritmus. Az ÁRUHÁZ és a BANK közötti üzenetek titkosítását biztosítja. Kulcs (<aruhazid>.des) registry bejegyzés (<aruhazid>.reg): A.des kulcs a titkosítás alapja, ezek az adatok szükségesek a titkosító modulnak, hogy a megfelelő stringet adja vissza. A DES kulcsot Win32 alatt a registry-ben is tárolni kell a HKEY_LOCAL_MACHINE\ SOFTWARE\CIB\EKI\Keys\<ÁRUHÁZId> registry kulcs bináris típusú DES nev értékében. A.reg megteszi a bevésést. Fizetőoldal eléréséhez szükséges URL-ek: Teszt szerver: áruház url: http://ekit.cib.hu:8090/market.saki vásárló url: https://ekit.cib.hu/customer.saki A csomagot zip formátumban küldi meg a Bank a Kártyaelfogadói szerződés 3. számú mellékletében található Üzemeltető kapcsolattartó e-mail címére. Amennyiben a csomag tartalmának valamely elemét nem kapta meg, kérjük, jelezze az címen. 1.2 Fogalmak A CIB internetes technológián alapuló elektronikus áruházrendszerének három fő szereplője a VÁSÁRLÓ, az ÁRUHÁZ, és a BANK. A BANK-kal történő kommunikáció azonban mindig az ÁRUHÁZ szintjén történik. BANK - A kártyatranzakció lebonyolítását végző pénzintézet (CIB Bank Zrt.) ÜGYINTÉZŐ - A szerződésben megjelölt kapcsolattartó a BANK részéről (Kártyaelfogadói szerződés 3. melléklet II. pont) ÁRUHÁZ - Az Interneten kereskedelmi tevékenységet folytató, a BANK-kal szerződött, pénzügyi kapcsolatban álló vállalkozás VÁSÁRLÓ - Az Interneten a virtuális ÁRUHÁZ-ban bankkártyájával vásárló személy Biztonság az adatkezelésben Az elektronikus kereskedelem bankkártyás fizetése során az adatokat elkülönítetten kezeltek, és így csak a megfelelő helyre juthatnak el: kártyaadatok közvetlenül a BANK-hoz jutnak el, így a kereskedő csak arról értesül, hogy a tranzakció teljesült-e; a vásárlóval, vásárlással, szolgáltatással, eladott termékkel kapcsolatos adatok pedig csak a kereskedő birtokába jutnak, a BANK ezekről nem szerez tudomást. Minden kapcsolatfelvétel és kommunikáció első szinten a VÁSÁRLÓ és az ÁRUHÁZ között zajlik, az ÁRUHÁZ-BANK és a VÁSÁRLÓ-BANK kapcsolat csak akkor jön létre, ha a vásárlási szándék 4. oldal
realizálódott és fizetésre került sor. A VÁSÁRLÓ minden adatot kizárólag az ÁRUHÁZ-zal közöl, a BANK számára releváns adatokat az ÁRUHÁZ juttatja el titkosítva a BANK-hoz jelen dokumentumban definiált protokoll szerint. Ez alól az egyetlen kivétel a VÁSÁRLÓ bankkártya adatainak kezelése, amit kizárólag csak a BANK tehet meg, megfelelő biztonsági követelményeknek eleget téve. A VÁSÁRLÓ bankkártyájának adatai semmilyen körülmények között sem kerülhetnek ki a BANKból (az ÁRUHÁZ-hoz sem). Az egyetlen információ, ami a kártyatranzakcióról visszajut az ÁRUHÁZ-hoz, az a tranzakció eredménye (az authorizáció sikeres vagy sikertelen volt). A tranzakció eredményéről az ÁRUHÁZ, és nem a BANK értesíti a vásárlót! A BANK mindössze elkéri a VÁSÁRLÓ kártyájának adatait és elvégzi a fizetési tranzakció engedélyeztetését (authorizáció). 1.3 A fizetési folyamat Jelen leírás a vásárlásnak csak a fizetési szakaszát érinti. E szerint a VÁSÁRLÓ már a megrendelés előtt áll, a fizetés lebonyolítását kívánja indítani. ÁRUHÁZ-onként változó lehet a megrendelési séma, a fizetés szempontjából csupán annyi jelentősége van, hogy a vevő összegyűjtse azokat az árucikkeket, melyek a vásárlás számszerű összegét fogják adni. A fizetési folyamat lépései: A dokumentációban gyakran található hivatkozás az alábbi pontokra. [0.] A VÁSÁRLÓ a böngészőben megadta az ÁRUHÁZ URL-jét, és megkapja az ÁRUHÁZ nyitó oldalát. Ha az ÁRUHÁZ regisztrálja és azonosítja ügyfeleit, akkor azonosítást kér. Sikeres bejelentkezés után a VÁSÁRLÓ megkezdheti az árucikkek kiválogatását. [1.] A válogatás befejezése után a VÁSÁRLÓ a Fizetés lehetőség kiválasztásával kéri a tranzakció lebonyolításának megkezdését. 5. oldal
[2.] Az ÁRUHÁZ adatbázisában tárolja a vásárlás jellemzőit, és a tranzakciót egyedi azonosítóval látja el (lásd: TRID), amely azonosító innentől kezdve a vásárlás egész tartama alatt minden lépésben szerepelni fog. Az előállított azonosítót a VÁSÁRLÓ regisztrált felhasználói nevével és a tranzakció összegével elküldi a BANK-nak. (Ha az adott ÁRUHÁZ nem regisztráltatja vásárlóit, a BANK-nak egy fiktív felhasználói nevet küldhet.) [3.] A BANK regisztrálja és ellenőrzi a tranzakciós kérést (lásd: MSGT 10, 11), és az eredményről értesíti az ÁRUHÁZ-at. Ekkor még csak a tranzakciókérés regisztrációja történik meg, amely átmeneti tárolásra kerül. A VÁSÁRLÓ a 4 5. lépésben érkezik majd a BANK-ba, hogy az ÁRUHÁZ által kért tranzakció végrehajtására engedélyt adjon. [4.] Ha a BANK válasza a tranzakciókérés sikertelenségét jelzi, a VÁSÁRLÓ az ÁRUHÁZ-tól erről értesítést kap, és a vásárlásnak vége szakad. A VÁSÁRLÓ természetesen újra próbálkozhat. A BANK válasza alapján az ÁRUHÁZ esetleg automatikusan újra kéri a tranzakció regisztrálását a BANK-tól.) Ha a BANK - válasza alapján - a tranzakciókérést sikeresen regisztrálta, az ÁRUHÁZ a VÁSÁRLÓ-t transzparens módon a tranzakció-azonosítóval ellátva a BANK-hoz irányítja. Ekkor az ÁRUHÁZ-VÁSÁRLÓ és ÁRUHÁZ-BANK kapcsolatot felváltja a VÁSÁRLÓ-BANK kapcsolat, az ÁRUHÁZ a 9. lépésnél kerül újra kapcsolatba a VÁSÁRLÓVAL. [5.] A BANK-ba érkező VÁSÁRLÓ URL-ben hozza magával az ÁRUHÁZ-tól kapott tranzakció azonosítót, amelynek alapján a BANK elveszi a 3. lépésben letárolt tranzakciókérést. 5.1. A BANK egy HTML oldalt helyez (lásd: MSGT 20, 21) a VÁSÁRLÓ elé, melyen szerepel a tranzakció összege, az ÁRUHÁZ neve, egyéb kiegészítő információk, valamint itt kell megadnia bankkártyája számát vagy kérnie a tranzakció megszakítását (amire ennél a pontnál van utoljára lehetősége). 5.2. A VÁSÁRLÓ a kitöltött nyomtatványt visszaküldi a BANK-nak, amely, ha a tranzakciót a nyomtatványon engedélyezték, megkezdi annak végrehajtását. [6.] Ha a VÁSÁRLÓ a tranzakció megkezdését jóváhagyta, a BANK elvégzi az authorizálást. Ez a lépés a VÁSÁRLÓ és az ÁRUHÁZ elől teljesen el van fedve, önálló kommunikációs csatornán keresztül zajlik. (Az authorizációs lehetőségeket lásd később.) [7.] Ha a VÁSÁRLÓ a tranzakció megszakítását kérte banki fizetőoldalon a Vissza gombra kattintott) -, a BANK bejegyzi a megszakítást, és nem authorizál. [8.] A BANK a VÁSÁRLÓ-t számára transzparens módon visszaküldi az ÁRUHÁZ-ba, természetesen most is csatolva a tranzakció azonosítóját. Ekkor az authorizáció eredményéről még nem közöl semmit. Az ÁRUHÁZ fogadja a visszatérő VÁSÁRLÓ-t, és a hozott tranzakció azonosító birtokában újra elveszi saját adatbázisából az adott vásárlás adatait, ellenőrzi azokat. [9.] Az ÁRUHÁZ újra felveszi a kapcsolatot a BANK-kal, és elkéri a tranzakció azonosítóhoz tartozó authorizációs eredményt majd kéri a tranzakció lezárását (lásd: MSGT 32).(Authorizáció: engedélykérés az összeg terhelésére) [10.] A BANK közli az ÁRUHÁZ-zal a tranzakció végeredményét és lezárja azt. [11.] Az ÁRUHÁZ közli a VÁSÁRLÓ-val a tranzakció eredményét, és lezárja azt. Innentől a VÁSÁRLÓ újra vásárolhat, vagy elhagyhatja az ÁRUHÁZ honlapját. [12.] Amennyiben az ÁRUHÁZ megadott időn belül (10 perc) nem hajtja végre a [10] lépést, a BANK reverzálást indít, azaz visszavonja a vásárló kártyáján a foglalást! [13.] Amennyiben a [9] lépés eredménye sikertelen, hibakezeléshez lásd a 3.sz mellékletet. 6. oldal
Megjegyzések: Az ÁRUHÁZ-BANK kapcsolatban saját titkosító eljárás felhasználásával a küldött adatok nyílt csatornán, de erősen titkosított formában utaznak. Ennek megoldásához ÁRUHÁZ oldali fejlesztésre van szükség. Gondoskodni kell a BANK birtokában lévő titkosító program esetleges más rendszerekre való portolásáról (jelenleg WinNT, AIX, Linux és Sun Solaris platformokon létezik). A dokumentációban alternatív megoldás található a titkosításra. A BANK-VÁSÁRLÓ kapcsolat minden esetben, egész idő alatt erős (128 bit) SSL, melyért a BANK felel. A BANK a VeriSign 128 bit SSL tanusítványát alkalmazza, így képes megfelelően erős titkosított kommunikációs csatorna létrehozására és folyamatos fenntartására. A BANK csak a fizetés megkezdésekor lép be a vásárlási folyamatba. A webáruház semmilyen olyan adatot nem ad át a BANK-nak, amivel azonosítható lenne a kosár tartalma, kizárólag az üzenettípusokban definiált paramétereket kell átadni.(lásd : üzenetek) A VÁSÁRLÓ bankkártyájának adatai, illetéktelenül nem kerülnek ki a BANK-ból. A BANK minden tranzakcióval kapcsolatos adatokat naplóz, melyet a tranzakcióval kapcsolatos vizsgálatok, reklamációk érdekében megőriz, és rendszeresen archivál. Miután a VÁSÁRLÓ a fizetést választotta az ÁRUHÁZ-ban, az elinduló tranzakciós folyamat a VÁSÁRLÓ számára szinte nem is látható. Az egész folyamat 12 lépésből áll, a VÁSÁRLÓ gyakorlatiban hármat érzékel közvetlenül, ezek: 1. A VÁSÁRLÓ az ÁRUHÁZ oldalán választja ki az árut/szolgáltatás, melynek összegét bankkártyás fizetéssel kívánja teljesíteni. 2. Ezt követően a VÁSÁRLÓ átkerül a BANK biztonságos fizetést garantáló oldalára, ahol a fizetés megkezdéséhez kártyaadatait szükséges kitöltenie. 3. A kártyaadatok megadását követően a Fizetés gombra kattintva indíthatja el a tranzakciót. A VÁSÁRLÓ a BANK fizetőoldaláról az ÁRUHÁZ-ba visszatérve értesül a vásárlás eredményéről, azaz arról, hogy a fizetés sikeres volt-e, vagy sem. FIGYELEM! A vásárló átirányítása az ÁRUHÁZ és a BANK között vagy a Location: név HTTP header mezővel, vagy a HTTP-EQUIV HTML meta tag-el történik (<meta HTTP-EQUIV= refresh CONTENT= [N]; URL=[URL] >, N lehetőleg 0 legyen, URL pedig a BANK/ÁRUHÁZ által megadott URL). A fizetési folyamat során nincsenek párhuzamos lépések, így nem alakulhat ki várakozási holtpont. Minden lépés sorban egymás után következik, és csak miután az egyik lezajlott, utána kerül sor a következőre. Egyetlen lépés kihagyására sincs lehetőség, mivel azok egymásra épülnek! Feltételezzük, hogy az ÁRUHÁZ-BANK és a (rejtett) BANK-HOST kapcsolat állandóan létező gyors fizikai hálózati kapcsolat. Figyelmen kívül hagyjuk az esetleges műszaki problémákat, mivel ezekre normál üzemszerű állapotban nem számítunk, így az egész folyamat időtartama elsősorban a VÁSÁRLÓ kapcsolódási sebességétől függ! Amennyiben az jó minőségű, gyors kapcsolat, a fizetési folyamat várhatóan nem lesz hosszú, az esetek legnagyobb részében az 1-től a 12. lépésig remélhetőleg nem lépi túl egy bankautomatából történő készpénzfelvétel átlagos időtartamát (nem számítva ide az 5.1. lépést, ahol a vásárló kártyaadatinak bevitelére várunk). Amennyiben a VÁSÁRLÓ internet kapcsolata lassú, az ÁRUHÁZ-BANK és BANK- 7. oldal
HOST kapcsolatot ez nem befolyásolja, azok továbbra is gyorsak maradnak, a VÁSÁRLÓ-nak pedig pontosan annyit kell várnia az oldalak letöltésére, mint amennyit egy átlagos HTML oldal esetén kellene várnia! (Ez persze mindig igaz, de lassú kapcsolat esetén fontossá válhat a protokollban a time-out-ok miatt.) Az ÁRUHÁZ a [10] lépésben újra küldi a BANK-nak a tranzakciós összeget. Erre azért van szükség, mert bizonyos esetekben, (ha az ÁRUHÁZ szoftvere ezt lehetővé teszi) a VÁSÁRLÓ a BANK-ba irányítás alatt vagy után, de még a tényleges kártyatranzakció előtt esetleg megváltoztathatja az ÁRUHÁZ-ban a kosár tartalmát, és ebből a kereskedőt esetleg kár érheti. Ha az adott tranzakcióhoz tartozó authorizáció sikeres volt, a BANK a [10.] lépésben másodszor elküldött tranzakciós összeget összeveti az authorizációs összeggel, és ha a kettő között eltérés van, akkor a tranzakciót megfelelő hibakóddal látja el, az ÁRUHÁZ-zal közli, hogy a tranzakció sikertelen, majd ún. reversal tranzakciót indít. Az ÁRUHÁZ-nak a BANK fizetőoldaláról történő visszatérést követően a következő adatokat kötelező megjelenítenie: o Válaszkód (RC) o Válaszüzenet (RT) o Tranzakció azonosító (TRID) o Engedélyszám (ANUM) A BANK az ún. Verified by VISA kártyáknál biztosítja a 3D-Secure protokollt. Ez a VÁSÁRLÓ számára egy extra átirányítást jelent a BANK fizetőoldaláról a kártyakibocsátó bankjának a biztonságos szerverére (az ÁRUHÁZ számára transzparens), ahol egy speciális kódot kell megadnia a tranzakció megerősítéséhez. Mivel a kártyakibocsátó bankhoz történő átirányítás után a BANK fizetőoldalát a VÁSÁRLÓ elhagyja (hasonlóan ahhoz az esethez, amikor az ÁRUHÁZ átirányítja a VÁSÁRLÓ-t a BANK-hoz), elképzelhető, hogy a tranzakció ezen a ponton megszakad. Emiatt is kötelező az ÁRUHÁZ oldaláról is bevezetni a 10 perc timeout-ot a tranzakcióra! Time-out esetén a tranzakció automatikusan sikertelen lesz! A tranzakció eredményének lekérdezését két üzenet is támogatja. A 32-es üzenet megerősíti a foglalást, míg a 33-as csupán információt szolgáltat. Ahhoz, hogy a tranzakció érvényesítésre kerüljön, a folyamat által megkövetelt pillanatban [10.] lépés kötelező a 32-es üzenet használata. A tranzakció lépéseinek lekérdezésére szolgál a 37-es üzenet. Sikeres lekérdezés esetén, a 38-as válaszüzenet RC mezője sikeres tranzakciót igazol vissza, ezzel 00 értéket vesz fel, a HISTORY mező pedig tartalmazza a lekérdezés pillanatáig bekövetkezett összes állapotot, egymástól vesszővel elválasztva. 8. oldal
2. PROBLÉMAKEZELÉS A kártyakibocsátó banknak jogában áll a BANK authorizációs kérését elutasítani. A VÁSÁRLÓ tájékoztatására ezért kötelező a válaszkódnak (RC) megfelelő hibalehetőségek kiíratása válaszüzenettel (RT). Részletesebb információt a VÁSÁRLÓ a kártyáját kibocsátó bank ügyfélszolgálatánál kérhet, a kártya hátoldalán található telefonszám felhívásával. Az ügyféllel való kapcsolattartás minden esetben a kártyaelfogadásra szerződött fél (ÁRUHÁZ) feladata. A BANK tranzakcióval kapcsolatos tájékoztatást közvetlenül csak saját, szerződött ügyfelei részére adhat. 9. oldal
3. AZ ÁRUHÁZ ÉS A BANK KÖZÖTTI PROTOKOLL Az ÁRUHÁZ és a BANK között HTTP-re épülő kommunikáció van érvényben. A kérések HTML FORM-hoz hasonló formátumban érkezhetnek a BANK-ba, de az adatok az URL kódolás előtt titkosítva, az URL kódolás után UUENCODE-olva vannak. Az ÁRUHÁZ-tól közvetlenül a BANK-ba irányuló kérések (2, 10), illetve a vezérlésátadások (4-5, 8-9) általános formátuma: http: //cím/script? PID=boltid&CRYPTO=ctype&DATA=uuencoded-data ahol Cím: Script: boltid: A Bank vagy az ÁRUHÁZ szerverének címe. A BANK két címet tart fenn a kérések kiszolgálására: egyet a BANK és ÁRUHÁZ közötti közvetlen kommunikációra, a másikat a VÁSÁRLÓ-k számára. Az ÁRUHÁZ-nak a VÁSÁRLÓ-t a második címre kell küldenie. A kéréshez tartozó script vagy program. Az ÁRUHÁZ és azonbelül a BOLT azonosítója. Ennek meg kell egyeznie a kérésben szereplő BoltID mezővel. 1 (DES) A kérés adatai. crypto uuencoded-data crypto=1: CRC32-vel, TripleDES-elve és uuencodolva A BANK ÁRUHÁZ-nak adott válaszai (3, 11) plain-text formában (HTTP Content-Type: text/plain), uuencodolva jutnak vissza az ÁRUHÁZ-ba, ugyanolyan formátumban, mint ahogyan az ÁRUHÁZ a kérdést feltette: URL kódolással, DES-elve, uuencode-olva. A válasz azonban nem URL-ben megy vissza, hanem content-ben. Tehát a BANK nem egy programot hív meg az ÁRUHÁZ oldalon, hanem a feltett kérdésre válaszol, mintha egy web böngészővel kommunikálna. PID=boltid&CRYPTO=ctype&DATA=uuencoded-data Ahol a BoltID, crypto és uuencoded-data mezők megegyeznek a kérésekben találhatóakkal. Tehát az ÁRUHÁZ-ba a válasz content-ben érkezik meg, de URL kódolt formában. A titkosításhoz használt kulcs rendszeres cseréje az ÁRUHÁZ-BANK között akár valamilyen fizikai adathordozón keresztül, akár az ÁRUHÁZ-BANK közötti kapcsolaton elképzelhető a mindenkori aktuális kulcs segítségével. A kulcs az áruház-rendszeren belül az ÁRUHÁZ-BANK kapcsolatra nézve egyedi. A kulcsokat rendszeresen cserélni kell, mely az ÁRUHÁZ-BANK csatorna használatával akár teljesen automatizálható. (A titkosítás megvalósításához a BANK az ÁRUHÁZ részére megállapodás szerint biztosítja a BANK által készített titkosító modult, példaprogramot (ez utóbbit forráskóddal) együtt. A titkosító modul jelenleg Win32, Linux, SUN Solaris, FreeBSD, és OpenBSD rendszereken használható, más platformokra történ portolást az ÁRUHÁZ-nak kell megoldania. A dokumentációban PHP és JAVA-s megoldási segítséget adunk.) 3.1 Az egyes mezők definíciója 3.1.1 Jelölések: A: Alfanumerikus N: Numerikus 3.1.2 Az adatmezők rövid összefoglalása 10. oldal
Mező megnevezése URL jelölés Hossz Típus Titkosítás típusa CRYPTO 1 N Üzenettípus MSGT 2 N Bolt ID PID 7 A TrID TRID 16 N Ügyfél ID UID 11 A Összeg AMO Max. 7 N Pénznem CUR 3 A Időpecsét TS 14 N Válaszkód RC 2 A Válasz szöveg RT 0-255 A Engedélyszám ANUM Max. 6 A Authorizáció típus AUTH 1 N URL URL Max. 255 A Nyelvkód LANG 2 A Történet HISTORY Max. 255 A 3.1.3 Titkosítás típusa (CRYPTO) A paraméter mindig 1 lesz, mivel a titkosító algoritmus a string titkosításánál azt automatikusan beállítja. 3.1.4 Üzenettípus (MSGT) Minden üzenetre különböző, ez azonosítja az egyes üzenetstruktúrákat. 3.1.5 ÁRUHÁZ azonosító (PID) Az ÁRUHÁZ azonosítója két részből áll: Áruházazonosító: Azonosítószám (PID): 3.1.6 Tranzakció azonosító (TRID) 3 karakter (3A). Az áruház hárombetűs azonosítója. Ez az azonosító az ügyfélazonosítóban (UID) is megjelenik. 4 karakter (4A). Az ÁRUHÁZ sorszáma. Véletlen szám, amit az ÁRUHÁZ készít a tranzakció kezdetekor, és a vásárlás befejezéséig azonosítja a tranzakciót mind az ÁRUHÁZ, mind a BANK oldalán. Egy TRID csak egyszer használható, azaz ha egy másik kereskedő lefoglalt egy TRID-et akkor az más kereskedő számára sem osztható újra ki, a véletlen szám generátorral elkerülik a foglalt TRID-re futás lehetőségét. Példa: For ($i=1;$i<=16; $i++) { $szam=rand(1,9); $trid.=$szam; } 3.1.7 Ügyfél azonosító (UID) A vásárló felhasználói azonosítója az áruházon belül. Adott vásárló kártyás tranzakcióinak egyértelmű azonosítását, illetve felhasználóhoz kapcsolódó vizsgálatok elvégzését teszi lehetővé. Javasolt a vásárló a honlapon történő regisztrációja során választott azonosítót hozzárendelni. 11. oldal
3.1.8 Összeg (AMO) A tranzakció összege. Forint alapú tranzakció esetén, igazítás nélkül. Csak egész szám lehet! Euró alapú tranzakció esetén, igazítás nélkül, két tizedesjegyig. Törtszámú összeget tizedesponttal kell elválasztani, két tizedesjegyig kell feltölteni a karaktereket (pl.: 10.20) FIGYELEM! Az EUR összeggel tötrténő tranzakció visszagazolásábam a tizedespont URL enkódolt formában jelenik meg ( %2E ) AMO értéket tartalmazó visszaigazoló üzenet HUF tranzakció esetén nem tartalmaz tizedesjegyeket, az EUR tranzakciók esetén igen. Amennyiben mindkettő fizetési devizanemet alkalmazza az ÁRUHÁZ, úgy külön kell választani a válaszüzenetek ÁRUHÁZ oldali feldolgozását. 3.1.9 Valutakód (CUR) A tranzakció pénznemének kódja. A rendszer jelenleg forint és euró alapon működik. Forint esetén használandó paraméter mindig HUF, euró tranzakció esetén az EUR. FIGYELEM! Ugyanazon a PID-en nem működhet együtt HUF és EUR alapú tranzakció. A HUF-ban beszedendő összeghez 0-val kezdődő PID szolgál (pl.: ABC0001), az EUR-ban beszedendő összeghez 1-gyel kezdődő PID szolgál (pl.: ABC1001). Amennyiben nem a megfelelő PID-hez kerül inicializálásra a tranzakció, úgy a rendszer RC=01 hibaüzenetet ad. Amennyiben az ÁRUHÁZ HUF-ban és EUR-ban is értékesít, úgy a fizetéshez legalább két PID-et szükséges, s az adott devizanemű fizetéshez az adott PID-et szükséges rendelni. Amennyiben az ÁRUHÁZ szerződéskötésekor nem jelölt meg a tranzakciók jóváírására euróban vezetett pénzforgalmi számlát, úgy a Bank alapértelmezettként csak a forint tranzakciók lebonyolítására alkalmas PID-et készíti el. Euró alapú tranzakciók lebonyolítására alkalmas PID-et szerződés-kiegészítés keretében van lehetőség igénybevenni. EUR tranzakció esetén nem tizedespont alkalmazása vagy nem két tizedesjegyig történő kitöltés RC=01 hibaüzenetet generál (pl.: 10,2) Tizedespontot és két tizedesjegyet kell alkalmazni. 3.1.10 Időpecsét (TS) A tranzakció időpecsétje. Formátuma: EEEEHHNNOOPPMM ahol: EEEE: év HH: hónap NN: nap OO: óra PP: perc 12. oldal
MM: másodperc 3.1.11 Válaszkód (RC) A 10-es üzenettípusban a BANK válasza: 00: A tranzakció bejegyezve, a BANK várja a VÁSÁRLÓ átirányítását. 01: A tranzakció bejegyzése sikertelen. A 31 és 33-as üzenettípusban a BANK-ban történt authorizáció, lényegében a teljes folyamat eredménye. 00 (OK) esetén a tranzakció el lett fogadva, tehát az ügyfél a tranzakció összegét kifizette. RC minden más értéke hiba, a tranzakció valamilyen okból történ megszakítását jelenti. 3.1.12 Válasz szöveg (RT) A Válaszkód (RC) változó hosszúságú, szövegformátumú leírása. Egyes válaszkódokhoz a BANK rövid szöveges információt közöl a válaszkód jelentéséről, melyeket a VÁSÁRLÓ tudomására kell hozni a BANK fizetőoldaláról történő visszatérés során. Válasz szöveg helyes megjelenítése érdekében a karakterkódolására a következőket javasoljuk: ISO-8859-2 (Latin2) ISO-8859-1 (Latin1) UTF-8 (Unicode) 3.1.13 Engedélyszám (ANUM) Authorizációs engedély száma. Ha az authorizáció megtörtént, és a tranzakció sikeres volt (RC=00), ez a mező tartalmazza a tranzakció engedélyszámát. Az ÁRUHÁZ ezt a számot köteles a VÁSÁRLÓ tudomására hozni. 3.1.14 Authorizáció típusa (AUTH) WEB authorizáció, amikor a vásárló a böngésző programban SSL csatornán hagyja jóvá a tranzakció végrehajtását, ill. ott adja meg bankkártyájának számát. 3.1.15 URL (URL) Áruház URL-je, ahova a BANK visszaküldi a vásárlót fizetés után. Mivel a banki szerver ezt az URL-t fogja paraméterezni a 21-es üzenettel, az URL mező nem lehet előre paraméterezett (tehát csak a http://server/path/program.ext forma megengedett). 3.1.16 Nyelvkód (LANG) A vásárló által az ÁRUHÁZ-ban kiválasztott nyelv. A fizetőoldal az adott nyelvkóddal (pl.: HU) fog megjelenni, ha létezik megfelelő HTML oldal a BANK szerverén. Jelenleg a következő nyelveken érhető el a fizetőoldal: Nyelvkód Nyelv HU DE EN IT FR PL PT CZ ES SK RO magyar német angol olasz francia lengyel portugál cseh spanyol szlovák román 13. oldal
3.1.17 Történet (HISTORY) A tranzakció lépéseit tartalmazó mező. A mezőben a tranzakció lépéseinek megfelel max. 2 karakter hosszú kódok szerepelnek, egymástól vesszővel elválasztva. A kódok jelentése a következő: Kód Jelentés 10 A vásárló megérkezett a fizetőoldalra 11 A vásárló engedélyezte a tranzakciót 12-13 A vásároló nem engedélyezte a tranzakciót 20 Authorizáció folyamatban 21 Sikeres authorizáció, vásárló visszaküldése a boltba 22 Sikertelen authorizáció, vásárló visszaküldése a boltba 30 Bolt megerősítette a terhelést, tranzakció vége 50 Time-out miatt reverzálás szükséges 52 A tranzakció reverzálása kijelölésre került 55 Reverzálás indítása 56 Sikeres reverzálás 57 Sikertelen reverzálás Példák: Sikeres authorizáció és lezárt tranzakció lépései: 10, 11, 20, 21, 30 Sikertelen authorizáció és lezárt tranzakció lépései: 10, 11, 20, 22, 30 Le nem zárt (vagyis sikertelen) tranzakciók esetei: Sikeres authorizáció, de nincs lezárás: 10, 11, 20, 21 Sikertelen authorizáció és nincs lezárás: 10, 11, 20, 22 Time out: 10 vagy 10, 11, 20, 21, 55, 56 vagy 10, 11, 20, 21, 55, 56, 30 Vásárló visszalépett a fizetőoldal Vissza gombjával a fizetőoldalról: 10,12, 30 3.1.18 Státusz (STATUS) A tranzakció teljesítés szerinti állapota. Míg a HISTORY mező a folyamat egyes lépéseit tartja nyilván, a STATUS mező a tranzakció analitikai állapotáról nyújt információt. Lehetséges értékei a következők: Kód Jelentés 0 A tranzakció még nem lett authorizálva 10 Tranzakció authorizálva 20 Tranzakció megbízás által terhelve (lásd MSGT 76) 30 Tranzakció automatikusan terhelt 40 Tranzakció terhelése visszavonva (lásd MSGT 74) 50 Tranzakció terhelés után visszautalva (lásd MSGT 78) 60 Tranzakció lezárva 99 Hibás kérés 3.2 Az egyes üzenetek struktúrája 3.2.1 (2. lépés) Fizetési tranzakció inicializálása (ÁRUHÁZ BANK, MSGT=10) Üzenettípus Mező neve MSGT URL jelölés 14. oldal
Bolt ID Tranzakció azonosító Ügyfél azonosító Összeg Valutanem Időpecsét Authorizáció típusa Nyelvkód ÁRUHÁZ URL PID TRID UID AMO CUR TS AUTH LANG URL MSGT értéke 10. http://eki(t).cib.hu:8090/market.saki? paraméterek 3.2.2 (3. lépés) Válasz fizetési tranzakció inicializálására (BANK ÁRUHÁZ, MSGT=11) Mező neve Üzenettípus Bolt ID Tranzakció azonosító Válaszkód MSGT értéke 11. RespCode értékei: 00: Sikeres. A BANK a kérést rögzítette. 01: Sikertelen 02: A TRID már használatban volt MSGT PID TRID RC URL jelölés 3.2.3 (4-5. lépés) Vásárló fizetésre a BANK-ba irányítva (ÁRUHÁZ BANK, MSGT=20) Mező neve Üzenettípus Bolt ID Tranazakció azonosító URL jelölés MSGT PID TRID MSGT értéke 20. https://eki(t).cib.hu/customer.saki? paraméterek 3.2.4 (8-9. lépés) Vásárló fizetés után az ÁRUHÁZ-ba irányítva (BANK ÁRUHÁZ, MSGT=21) MSGT értéke 21. Mező neve Üzenettípus Bolt ID Tranzakció azonosító URL jelölés MSGT PID TRID 3.2.5 (10. lépés) Authorizáció eredményének lekérdezése, tranzakciós folyamat lezárása (ÁRUHÁZ-BANK, MSGT=32) Mező neve Üzenettípus Bolt ID Tranzakció azonosító Bolt által ismert összeg URL jelölés MSGT PID TRID AMO MSGT értéke 32. http://eki(t).cib.hu:8090/market.saki? Paraméterek 15. oldal
FIGYELEM! Minden tranzakciót le kell zárni az MSGT=32-es üzenettel! 3.2.6 (11. lépés) Authorizáció eredménye (BANK ÁRUHÁZ, MSGT=31) Mező neve Üzenettípus Bolt ID Tranzakció azonosító Válaszkód Válasz szöveg Engedélyszám Összeg MSGT értéke 31. RC értékei: 00: Sikeres tranzakció bármi más: Sikertelen tranzakció URL jelölés MSGT PID TRID RC RT ANUM AMO 3.2.7 Authorizációs információkérés (ÁRUHÁZ BANK, MSGT=33) Mező neve Üzenettípus Bolt ID Tranzakció azonosító Bolt által ismert összeg URL jelölés MSGT PID TRID AMO MSGT értéke 31. http://eki(t).cib.hu:8090/market.saki? paraméterek RC értékei: PR: Tranzakció folyamatban TO: Time-out (reverzálás megtörtént) 00: Sikeresen authorizált tranzakció bármi más: Sikertelenül authorizált tranzakció FIGYELEM! A tranzakciót NEM zárja le, csak információt hordoz annak állapotáról! Csak abban az esetben kell használni, ha a webáruház által indított tranzakció lezárására nincs banki válasz! Ez csak a time out esetén fordul elő. 3.2.8 Tranzakció lépéseinek lekérdezése - Történet (ÁRUHÁZ BANK, MSGT=37) Üzenettípus Bolt ID Mező neve URL jelölés MSGT PID 16. oldal
Tranzakció azonosító TRID Bolt által ismert összeg AMO MSGT értéke 37. http://eki(t).cib.hu:8090/market.saki? Paraméterek 3.2.9 Válasz a tranzakció lépéseinek lekérdezésére (BANK ÁRUHÁZ, MSGT=38) Mező neve Üzenettípus Bolt ID Tranzakció azonosító Tranzakciós lépések Kérés eredménye MSGT értéke 38. RC értékei: 00: Sikeres lekérdezés 01: Sikertelen lekérdezés URL jelölés MSGT PID TRID HISTORY RC 3.2.10 A Tranzakcó adatainak/állapotának lekérdezése, visszautalás kezdeményezése (ÁRUHÁZ-BANK, MSGT=70) Paraméter Hossz PID 7 TRID 16 MSGT 2 AMO Max 7 MSGT értéke 70. http://eki(t).cib.hu:8090/market.saki? paraméterek Válasz a lekérdezésre (BANK ÁRUHÁZ, MSGT=71) Paraméter Hossz PID 7 TRID 16 MSGT 2 RC 2 AMO Max 7 Status 2 MSGT értéke 71. RC értékei: 00: Sikeres lekérdezés 01: Hibás paraméterek (ebben az esetben a Status mező értéke 99) Status: a paramétereket lásd 5. Visszautalás fejezete 17. oldal
3.2.11 Még nem terhelt tranzakciók visszavonása (ÁRUHÁZ-BANK, MSGT=74) Paraméter Hossz PID 7 TRID 16 MSGT 2 AMO Max 7 MSGT értéke 74. http://eki(t).cib.hu:8090/market.saki? paraméterek FIGYELEM! MSGT=70-es üzenettel ellenőrizni kell, indítható-e a visszavonás. A banki válasz satus kódja a mérvadó. Ha Status=10, akkor az MSGT=74-gyel indítható a visszavonás. Kizárólag napi banki zárást megelőzően 18:00-ig lehetséges a teljesítése. Válasz a lekérdezésre (BANK ÁRUHÁZ, MSGT=75) Paraméter Hossz PID 7 TRID 16 MSGT 2 AMO Max 7 Status 2 MSGT értéke 75. RC értékei: 00: Sikeres reverzálás 01: Hibás paraméterek (ebben az esetben a Status mező értéke 99) 3.2.12 Terhelés (banki zárás) után, tétel visszautalása tranzakció beállított összegével (ÁRUHÁZ-BANK, MSGT=78) Paraméter Hossz PID 7 TRID 16 MSGT 2 AMO Max 7 MSGT értéke 78. http://eki(t).cib.hu:8090/market.saki? paraméterek AMO: A terhelt összeg Válasz a lekérdezésre (BANK ÁRUHÁZ, MSGT=79) Paraméter Hossz PID 7 18. oldal
TRID 16 MSGT 2 AMO Max 7 RC 2 RT 255 MSGT értéke 79. RC értékei: 00: Sikeres tranzakció 01: Hibás paraméterek (ebben az esetben a Status mező értéke 99) A visszautalás az MSGT=80 üzenetben beállított összegre történik. 3.2.13 Terhelés (banki zárás) után, visszautalandó összeg beállítása (ÁRUHÁZ- BANK,MSGT=80) Paraméter Hossz PID 7 TRID 16 MSGT 2 AMOORIG Max 7 AMONEW Max 7 MSGT értéke 78. AMOORIG: eredeti összeg (alapértelmezetten a terhelt összeg) AMONEW: új visszautalandó összeg (0<AMONEW<=AMOORIG) http://eki(t).cib.hu:8090/market.saki? paraméterek Válasz a lekérdezésre (BANK ÁRUHÁZ, MSGT=81) Paraméter Hossz PID 7 TRID 16 MSGT 2 AMO Max 7 STATUS 2 3.3 A [32] üzenet típusról bővebben Az ÁRUHÁZ és a BANK közötti kommunikáció utolsó lépéseként, az ÁRUHÁZ elkéri a BANK-tól az authorizáció eredményét, és a BANK válasza alapján mind az ÁRUHÁZ, mind a VÁSÁRLÓ tudomást szerez az eredményről. Bizonyos esetekben az ÁRUHÁZ rendszere megengedheti, hogy a VÁSÁRLÓ a kosár tartalmát módosítsa, a [4] és [7] lépések között. Ekkor az ÁRUHÁZ más tranzakciós összegről tud, mint amit a BANK authorizál, így ez az ÁRUHÁZ-nak anyagi kárt jelenthet. Ennek kiküszöbölésére a BANK-ban a [30]-as üzenettípust felváltja a [32]-es, ami a [30]-hoz képest annyi különbséget jelent, hogy az ÁRUHÁZ az üzenetbe beleteszi az általa aktuálisan ismert tranzakciós összeget. A BANK ezt összeveti a ténylegesen authorizált összeggel. Amennyiben az összegek között eltérés van, és a BANK által nyilvántartott összegre sikeres authorizáció történt (sikeres szó itt úgy értendő, hogy a tranzakció elfogadásra került), a BANK egy ún. reverzál (visszavonás) tranzakciót indít (a tranzakció BANK által ismert - eredeti - összegével), és az áruháznak az R0 hibakódot adja vissza. A reverzál tranzakció eredményeként a VÁSÁRLÓ kártyájához tartozó számláján terhelés nem fog bekövetkezni, az 19. oldal
ÁRUHÁZ pedig az R0 hibakód alapján a vásárlást sikertelennek minősíti és lezárja. Az ÁRUHÁZ-nak lehetősége van a BANK által beállított time-out időn belül a tranzakció eredményét többször is lekérdezni. Ilyenkor, ha a második, vagy az azt követő lekérdezések összegének az ÁRUHÁZ mást ad meg, mint az első lekérdezésben küldött összeg, úgy a BANK az újbóli lekérdezés összeg mezőjét figyelmen kívül hagyja. Ilyenkor egy R1 hibakódot küld vissza az ÁRUHÁZ-nak, ami azt jelenti, hogy a tranzakció (authorizáció) sikeres volt, de nem az ÁRUHÁZ által a [32] lekérdezésben újonnan megadott összegére, hanem a legelső [32]-es típusú lekérdezésre. Ez az eset valószínűsíthetően programhiba vagy külső betörési kísérlet jele, így az R1 hibakód feltétlenül alapos kivizsgálást igényel. Amennyiben az authorizáció sikertelen volt, akkor az ÁRUHÁZ által küldött összegnek tulajdonképpen már nincs jelentősége. A válasz [31] üzenetben a BANK minden esetben küldi a tranzakció BANK által nyilvántartott összegét. 3.4 A BANK szerverének válaszai A BANK szervere kétféle típusú választ küld, attól függően, hogy a válaszkód az adatbázisban vagy a webszerveren generálódott. 1. Ha sikerül a kapott adatok kititkosítása és értelmezése a válasz az adatok ellenőrzéséből adódik. Amennyiben az adatfeldolgozás során a szerver nem talált hibát, akkor a válaszkód (RC) MSGT=11 esetén mindig 00, MSGT=31 esetén az authorizációtól függ válaszkód, és a válasz az üzenettípusnak megfelel URL struktúra szerint kerül a klienshez, tehát a szerver az adatokat befogadta. Ha az adatokban hibát talált, de az adatok értelmezhetőek voltak (megfeleltek az adott üzenettípus specifikációjának), akkor a válasz az üzenettípusnak megfelel URL strukturában megy vissza a hívónak, és RC a hibakódot tartalmazza. 2. Ha a kapott http szint adatok feldolgozása valamilyen ok miatt nem sikerült (pl. az adatok dekódolása, vagy az üzenet nem felelt meg a specifikációnak), akkor a válasz nem a definiált üzenettípusban megy vissza, hanem RC=XNN formában, ahol XNN a hibakód. Ez akkor is érvényes, ha az adatokat a VÁSÁRLÓ hozta, tehát ez egyben azt is jelenti, hogy a fenti hibakód a böngészőjében jelenik meg, és a vezérlés nem fog visszakerülni az ÁRUHÁZ-nak. Pl. ha egy kérés definiálatlan üzenettípussal érkezik (pl. MSGT=74 a BANK számára ismeretlen), akkor a válasz RC=S03 lesz, clear text formában, egyszerű content-ben. 3.5. Üzenettípusban definiálatlan hibakódok RC=S01: RC=S02: RC=S03: RC=S04: RC=S05: RC=S06: RC=S07: RC=D01: RC=D02: RC=D03: RC=D04: RC=D05: Hiba a kapott adatok fogadásakor. Hiba az adatokban. Értelmezhetetlen kérés. Adatbázis hiba. Hiba a feldolgozásban. Kriptográfiai hiba. Titkosítás nélkül küldött paraméterlista. Rossz paraméter. Értelmezhetetlen kérés. Hibás sorrend. (Nem a megfelel üzenettípusú kérés jött.) Ismétlés nem engedélyezett (Az adott üzenettípusú kérés egyszer már ki ett szolgálva). Az üzenettípushoz tartozó kérés már ki lett szolgálva, a folyamat ezen a 20. oldal
RC=D06: RC=D07: RC=D08: szakaszon már túljutott. Ismeretlen tranzakció. Hibás adatformátum. Hiba az adatokban 21. oldal
4. A CIB BANK FIZETÉSI FOLYAMATÁNAK RÉSZLETES LEÍRÁSA Ebben a részben SAKI leírás kiterjesztett változata található példákkal illusztrálva. A dokumentum gyakran áthivatkozik a SAKI korábbi részeire, ezért mindenképpen szükséges annak elolvasása, az itt található információk segítséget nyújtanak az integráció egyszerűsítéséhez, de a fejlesztés minden esetben egyedi finomhangolást igényel. A leírás a szerződéskötést követő állapotból indul és az élesítés befejezéséig tart. A következő lépésekre tér ki részletesen: Tesztkulcs, titkosító modul, titkos kulcs eljuttatása az ÁRUHÁZ fejlesztőjének Üzenettípusok részletes tárgyalása Titkosító modul használata, összeállított stringek en- és dekódolás Csatlakozás titkosított stringek használatával Élesítés kritériumai (technikai és üzleti) Éles kulcs átvétele 4.1 Tesztkulcs, titkosító modul, titkos kulcs eljuttatása az ÁRUHÁZ fejlesztőjének A szerződés 3. számú melléklete tartalmazza az Üzemeltető kapcsolattartó személy (továbbiakban Üzemeltető) nevét és elérhetőségét (telefonszám, e-mail cím). Itt azt a személyt kell megjelölni, aki a fizető modul technikai integrációját végzi, valamint a rendszer működésével kapcsolatban a BANK-kal konzultációt folytat A BANK a szerződéskötést követően erre a címre küldi ki a bank a következő állományokat: Titkosító modult letölthető link Titkosításhoz szükséges kulcs: <áruház három betűs azonosítója>.des Az integrációhoz szükséges dokumentációk, tájékoztatók, logók A levél kézbesítése egyben azt is jelenti, hogy a BANK részéről elkészültek a tesztszerveren a szükséges bejegyzések, az ÁRUHÁZ csatlakozni tud a tesztszerverhez. Az ÁRUHÁZ-nak az első feladata a BANK felé akkor keletkezik, amikor a vásárló a fizetést kezdeményezi. Minden ezt megelőző lépést (regisztrálás, árukiválasztás, navigáció az oldalon, stb.) az ÁRUHÁZ-nak kell leprogramozni, a BANK ennek funkcionalitást ellenőrzi, a működését nem tudja befolyásolni. 4.2 Első lépés: tranzakció inicializálása Az MSGT=10 üzenetet kell első lépésben összeállítani a következő példa alapján: CRYPTO=1&MSGT=10&PID=<BOLTID>0001&TRID=5718203720023838&UID=BBBABCDEFG H&AMO=10&CUR=HUF&TS=20081018113054&AUTH=0&LANG=HU&URL=www.valaszurl.hu/v alasz.html CRYPTO =1 MSGT=10 PID=<BOLTID>0001 minden esetben 1 lesz, a titkosító modul automatikusan beállítja Az üzenetek kódja Az üzemeltetőnek küldött levélben meghatározott PID, struktúrája 3 alfabetikus és 4 numerikus adat. Az első három karakter az ÁRUHÁZ-at azonosítja, a számok pedig az ÁRUHÁZ-on belül található boltot. Amennyiben egy ÁRUHÁZ szeretne egy másik profillal újabb boltot indítani, egy szerződés kiegészítést követően van erre lehetősége. Ebben az esetben nem kell új titkosító 22. oldal
TRID=5718203720023838 UID=BBBABCDEFGH AMO=10 CUR=HUF TS=20081018113054 AUTH=0 Minden esetben 0 LANG=HU URL=www.valaszurl.hu/val asz.html kulcsot használni (tikosításról bővebben 4.3 fejezetben ). Véletlen szám, amit az ÁRUHÁZ készít a tranzakció kezdetekor, és a vásárlás befejezéséig azonosítja a tranzakciót mind az ÁRUHÁZ, mind a BANK oldalon. Egy TRID csak egyszer használható, amennyiben egy sikeres inicializáció megtörtént egy TRID-del, többet az már nem használtató. Egy TRID alkalmazása a rendszer szempontjából egyszer lehetséges, vagyis egy ÁRUHÁZ által lefoglalt TRID-et nem lehet egy másik ÁRUHÁZ-nak használni. Minden esetben véletlen szám generátorral kell előállítani a TRID-et. Javasoljuk a három próbálkozást, ez szinte teljesen kizárja a foglalt TRID-re futást Első 3 karaktere a PID első 3 karaktere. A maradék 8 karakter az ügyfél azonosítója az ÁRUHÁZ-on belül. Összeg forintban megadva egész számra kerekítve, euróban megadva törtszámú összeget tizedesponttal kell elválasztani, két tizedesjegyig (pl.: 10.20). Az ÁRUHÁZ feltűnteti árait egyéb devizanemben is. Az idegen devizanem összeg feltűntetéséről bővebben a 4.4-es fejezetben olvashat. A tranzakció devizanemének kódja, amely HUF vagy EUR! A tranzakció időpecsétje. Formátuma: EEEEHHNNOOPPMM, A vásárló által az ÁRUHÁZ-ban kiválasztott nyelv. A fizetőoldal az adott nyelvkóddal (pl. HU) fog megjelenni, ha létezik megfelelő HTML oldal a BANK szerverén. Jelenleg a következő nyelvek érhetőek el: HU DE EN IT FR PL PT CZ ES RO SK magyar német angol olasz francia lengyel portugál Cseh Spanyol Román Szlovák ÁRUHÁZ URL-je, ahova a BANK visszaküldi a vásárlót fizetés után. Mivel a banki szerver ezt az URL-t fogja paraméterezni a 21-es üzenettel, az URL mező nem lehet előre paraméterezett (tehát csak a http://server/path/program.ext forma megengedett). 23. oldal
4.3 Második lépés: az összeállított üzenet titkosítása 4.3.1 SAKIDE programmal történő kódolás Nagyon fontos a következő pár gondolat a titkosítás megkezdése előtt: A BANK és az ÁRUHÁZ között csak titkosított módon lehetséges a kommunikáció. Sok esetben a tárhely szolgáltatók nem engedélyezik a parancssorból futtatható programok végrehajtását. Mivel a titkosító program szabványos 3DES algoritmust használ, a BANK nem ragaszkodik az általa kiküldött program használatához, ezért a forráskodót is a rendelkezésre bocsátjuk. A BANK-ból kapott üzenet is titkosítva érkezik, ami ugyancsak a titkosító programmal lehet visszafejteni. Az SAKIDE program a CIB titkosító moduljához egy egyszerű front-end program, amely e dokumentumban specifikált formátumú adatok titkosítására és visszafejtésére szolgál. A program alapértelmezetten a standard inputról várja az adatokat, az eredményt a standard outputra küldi. Paraméterek: -e a program titkosító módban fut, a bemenete EKI specifikáció szerinti URL formában legyen -d EKI spec. szerint titkosított dat visszafejtése -i Kulcsinformáció kérése. -m megadása szükséges. -j -i esetén akkor is kiírja a kulcsinformációt, ha annak értelmezése hibás. -m Kulcsazonosító. -p Kulcsfile helye, a filenév nélkül. Alapértelmezett "./" -v Üzenetek a stderr-ra. -s A feldolgozandó adatot nem a standard inputról várja, hanem itt kell megadni paraméterként idézőjelek között. -S Rendszerinformációk, ha a program GNU libc-vel volt fordítva. -u URL dekódolást végez a kititkosítás előtt. -v Verziószám megjelenítése. Legegyszerűbb módja a titkosítás kipróbálásának, ha egyszerű DOS promptban hívjuk meg az eljárást, ehhez másoljuk egy könyvtárba a következő file-okat az ekicrypt_r1.1\ekide_precompiled és az ekicrypt_r1.1\libekicrypt\win2k könyvtárakból (BoltID a BANK-tól kapott 3 betűs azonosító): <boltid>.des <boltid>.reg sakicrypt.dll sakide.exe
//kulcsfile adatai c:\teszt>sakide -i -m <boltid> Key ID: <BOLTID> Key path:./ Key size: 38 ID (internal): EKI Version: 2 Market ID (internal): <BOLTID> Creation Time: Mon Nov 29 16:56:52 1999 //Titkosítás meghívása c:\\teszt>sakide s "PID=CIB0001&MSGT=10&TRID=0000000343264803&UID=uid0001&AMO=1990&C UR=HUF&TS=19990428110732&AUTH=0&LANG=HU&URL=http://www.valami.hu/e ki.cgi" //eredmény PID=<BOLTID>0001&CRYPTO=1&DATA=1Cp4Uo3%2BXGkA7jvB2x98543umpgus6 hz1lzrvmzpv3dl0sldwa88 1oL2kW595PNDflgxM%2FzxXnZf31pyg07LbekkCSgIRbjc6vU9vszdF9KM%2FyjgRa SGSB%2F9SVsAb7 jgf3nvscer41crijoaiqwvksbtp9wnntaswdtm2ynub6entsamhkft6aym6i909niyh 6iXpKhwd7zYHq JlMRSomAIC //Visszafejtés meghívása c:\teszt>sakide -d -s "PID=<BOLTID>0001&CRYPTO=1&DATA=1Cp4Uo3%2BXGkA7jvB2x98543umpgus 6hZ1LzrVmZpv3DL0SLDWA881oL2kW595PNDflgxM%2FzxXnZf31pyg07LbekkCSgI Rbjc6vU9vszdF9KM%2FyjgRaSGSB%2F9SVsAb7jgF3nVSceR41CrIjoAIqwvKsBtP9 WNNtASWdTM2YNuB6EntsamhKft6AyM6i909nIyH6iXpKhwd7zYHqJlMRSomAIC" //eredmény PID=<BOLTID>0001&MSGT=10&TRID=0000000343264803&UID=uid0001&AMO=1 990&CUR=HUF&TS=199904 28110732&AUTH=0&LANG=HU&URL=http://www.valami.hu/eki.cgi A következő példa azt mutatja, hogyan lehet a titkosítást meghívni PHP-ban. Fontos, hogy bármilyen megoldás elfogadott, jelen példa csak demonstráció! <?php $amit="pid=<boltid>0001&msgt=10&trid=0000000343264803 &UID=uid0001&AMO=1990&CUR=HUF&TS=19990428110732 &AUTH=0&LANG=HU&URL=http://www.valami.hu/eki.cgi"; $exec = "/home/sakide.static -v -s \"".$amit."\""; exec($exec,$out,$x); print_r( $out); 25. oldal
print $x;?> A fenti példában az exec parancs a használatos. Előfordulhat, hogy ez a parancs tiltott a tárhely szolgáltatóknál. Ilyen esetek kapcsán javasoljuk a titkosítást PHP-ben vagy JAVA-ban megoldani. A következő példa scriptek előbb említett függvényekkel történő titkosítást mutatják be, amit természetesen az üzemeltető a rendszerhez való illesztésnek megfelelően alakíthat át. 4.3.2 PHP nyelven (>PHP4) történő titkosítási kódrészlet: A dokumentációs csomag Tutorial mappájában található php-s megvalósítása a titkosításnak, azonban ez a változat csak iránymutató segédlet, nem hivatalos banki program. Ekicrypt mappában megtalálható a C forráskód, ez alapján bárki elkészítheti az algoritmust bármilyen nyelven, a bank nem ragaszkodik az általa kiadott program használatához, szabvány 3DES algoritmust kell alkalmazni. A kulcs felépítése a következőképpen néz ki: Az utolsó 24 byte-ot tekintve az 1-8. az első kulcs 9-16. kettes kulcs 17-24. az init vektor. <? /* Titkosítás a saki protokoll alapján Paraméterek: $plaintext: a titkosítandó string $keyfile: a titkosításhoz szükséges kulcsfile neve Visszatérő érték: A titkosított üzenet */ function ekiencodeurl($plaintext,$keyfile) { $f=fopen($keyfile,"r"); $keyinfo=fread($f,38); fclose($f); $k1=substr($keyinfo,14,8); $k2=substr($keyinfo,22,8); $iv=substr($keyinfo,30,8); $key=$k1.$k2.$k1; $arr=split("&",$plaintext); $outs=""; $pid=""; for ($i=0;$i<count($arr);$i++) { if (strtoupper($arr[$i])!="crypto=1") $outs.="&".$arr[$i]; if (substr(strtoupper($arr[$i]),0,4)=="pid=") $pid=substr(strtoupper($arr[$i]),4,7); } 26. oldal
} /* $outs=substr($outs,1); $outs=rawurlencode($outs); $outs=str_replace("%3d","=",$outs); $outs=str_replace("%26","&",$outs); $crc=str_pad(dechex(crc32($outs)),8,"0",str_pad_left); for ($i=0;$i<4;$i++) $outs.=chr(base_convert(substr($crc,$i*2,2),16,10)); $pad=8-(strlen($outs) % 8); for ($i=0;$i<$pad;$i++) $outs.=chr($pad); $td=mcrypt_module_open("tripledes","","cbc",""); mcrypt_generic_init($td,$key,$iv); $outs=mcrypt_generic($td,$outs); mcrypt_module_close($td); $pad=3-(strlen($outs) % 3); for ($i=0;$i<$pad;$i++) $outs.=chr($pad); $outs=base64_encode($outs); $outs=rawurlencode($outs); $outs="pid=".$pid."&crypto=1&data=".$outs; return $outs; Kititkosítás a saki protokoll alapján Paraméterek: $crypto: a kititkosítandó string $keyfile: a titkosításhoz szükséges kulcsfile neve Visszatérő érték: A kititkosított üzenet, vagy crc hiba esetén üres string */ Function ekidecodeurl($crypto,$keyfile) { $f=fopen($keyfile,"r"); $keyinfo=fread($f,38); fclose($f); $k1=substr($keyinfo,14,8); $k2=substr($keyinfo,22,8); $iv=substr($keyinfo,30,8); $key=$k1.$k2.$k1; $arr=split("&",$crypto); $outs=""; $pid=""; for ($i=0;$i<count($arr);$i++) { 27. oldal
if (substr(strtoupper($arr[$i]),0,5)=="data=") $outs=substr($arr[$i],5); if (substr(strtoupper($arr[$i]),0,4)=="pid=") $pid=substr(strtoupper($arr[$i]),4,7); } $outs=rawurldecode($outs); $outs=base64_decode($outs); $lastc=ord($outs[strlen($outs)-1]); $validpad=1; for ($i=0;$i<$lastc;$i++) if (ord(substr($outs,strlen($outs)-1-$i,1))!=$lastc) $validpad=0; if ($validpad==1) $outs=substr($outs,0,strlen($outs)-$lastc); $td=mcrypt_module_open("tripledes","","cbc",""); mcrypt_generic_init($td,$key,$iv); if(!empty($outs)) // ha az $outs valtozoban van adat $outs=mdecrypt_generic($td,$outs); mcrypt_module_close($td); $lastc=ord($outs[strlen($outs)-1]); $validpad=1; for ($i=0;$i<$lastc;$i++) if (ord(substr($outs,strlen($outs)-1-$i,1))!=$lastc) $validpad=0; if ($validpad==1) $outs=substr($outs,0,strlen($outs)-$lastc); $crc=substr($outs,strlen($outs)-4); $crch=""; for ($i=0;$i<4;$i++) $crch.=str_pad(dechex(ord($crc[$i])),2,"0",str_pad_left); $outs=substr($outs,0,strlen($outs)-4); $crc=str_pad(dechex(crc32($outs)),8,"0",str_pad_left); if ($crch!=$crc empty($outs)) return ""; $outs=str_replace("&","%26",$outs); $outs=str_replace("=","%3d",$outs); $outs=rawurldecode($outs); $outs="crypto=1&".$outs; return $outs; } // Példa a használatra az CIB egy példa, a bank által küldött tesztkulcs nevére cserélje ki. (A példában a CIB.des kulcs a használatos.) /* $cleartext="pid=cib0001&crypto=1&msgt=10&trid=1234123412341234&uid=cib00 28. oldal
000001&LANG=HU&TS=19700108000006&AUTH=0&AMO=10000&URL=http://localhost/"; echo "Cleartext: ".$cleartext."<br>"; $crypto=ekiencodeurl($cleartext,"cib.des"); echo "Crypted: ".$crypto."<br>"; $cleartext2=ekidecodeurl($crypto,"cib.des"); echo "Cleartext: ".$cleartext2."<br>";?> */ 4.3.3 JAVA nyelven történő titkosítási kódrészlet: Kódolás: public String encode(string s){ byte[] bindata; try{ CRC32 crc=new CRC32(); crc.update(s.getbytes()); long c=crc.getvalue(); int len=s.length()+4; len+=8-len%8; bindata=new byte[len]; byte[] b=s.getbytes(); int i; for(i=0; i<b.length; i++){ bindata[i]=b[i]; } bindata[i++]=(byte)((c>>24)&0xff); bindata[i++]=(byte)((c>>16)&0xff); bindata[i++]=(byte)((c>>8)&0xff); bindata[i++]=(byte)(c&0xff); (s.length()+4)); bindata[i]=padding; } byte padding=(byte)(len- for(; i<len; i++){ DESedeKeySpec keyspec = new DESedeKeySpec(binKey); SecretKeyFactory keyfactory = SecretKeyFactory.getInstance("DESede"); SecretKey deskey = keyfactory.generatesecret(keyspec); ivvector = new IvParameterSpec(iv); IvParameterSpec 29. oldal