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. 1.1 1.2 1.3
A RENDSZER RÖVID ELMÉLETI ÁTTEKINTÉSE ................................................................ 4 Csomag tartalma: ............................................................................................................................ 4 Fogalmak......................................................................................................................................... 4 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ÁZBANK, 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ÁZBANK, 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. 4.1 4.2 4.3
A CIB BANK FIZETÉSI FOLYAMATÁNAK RÉSZLETES LEÍRÁSA ....................................22 Tesztkulcs, titkosító modul, titkos kulcs eljuttatása az ÁRUHÁZ fejlesztőjének................................ 22 Első lépés: tranzakció inicializálása................................................................................................ 22 Második lépés: az összeállított üzenet titkosítása........................................................................... 24
[email protected]
2. oldal
4.3.1 4.3.2 4.3.3 4.3.4 4.3.5 4.4 4.5 4.5.1 4.5.2 4.6 4.7
5. 5.1
6. 6.1 6.2 4.1 4.2 4.3 4.4
SAKIDE programmal történő kódolás ............................................................................................. 24 PHP nyelven (>PHP4) történő titkosítási kódrészlet: ...................................................................... 26 JAVA nyelven történő titkosítási kódrészlet: ................................................................................... 29 Fizetőoldali lépések folyamata ....................................................................................................... 33 Time-out miatti reverzálási folyamat leírása:................................................................................... 34 Forinttól és eurótól eltérő devizanemben feltüntetett árakról ........................................................... 35 Élesítés feltételei............................................................................................................................ 36 Logók megjelenítése...................................................................................................................... 36 ÁRUHÁZ működésre vonatkozó követelményei ............................................................................. 37 Élesítési kérés ............................................................................................................................... 39 Élesítés.......................................................................................................................................... 40
VISSZAUTALÁS FOLYAMATA ............................................................................................41 Visszautalás lépései: ..................................................................................................................... 41
A CIB TITKOSÍTÓ MODULJA...............................................................................................45 Az ekiCrypt feladata és használatának feltételei ............................................................................. 45 Titkosítás specifikációja (ekiEncodeUrl) ......................................................................................... 45 Visszafejtés az ekiCrypt-el (ekiDecodeUrl) ..................................................................................... 46 Kulcs struktúra (TKeyInfo).............................................................................................................. 47 Kulcsinformációk lekérdezése (ekiGetKeyInfo) ............................................................................... 47 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
[email protected]
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
[email protected] 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
[email protected]
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.
[email protected]
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 természetesen most is csatolva a tranzakció eredményéről még nem közöl semmit. Az ÁRUHÁZ hozott tranzakció azonosító birtokában újra elveszi adatait, ellenőrzi azokat.
módon visszaküldi azonosítóját. Ekkor fogadja a visszatérő saját adatbázisából
az ÁRUHÁZ-ba, az authorizáció VÁSÁRLÓ-t, és a az adott vásárlás
[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.
[email protected]
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
[email protected]
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.
[email protected]
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.
[email protected]
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:
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. Script: A kéréshez tartozó script vagy program. boltid: Az ÁRUHÁZ és azonbelül a BOLT azonosítója. Ennek meg kell egyeznie a kérésben szereplő BoltID mezővel. crypto 1 (DES) uuencoded-data •A kérés adatai. • 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: N:
Alfanumerikus Numerikus
3.1.2 Az adatmezők rövid összefoglalása
[email protected]
10. oldal
Mező megnevezése Titkosítás típusa Üzenettípus Bolt ID TrID Ügyfél ID Összeg Pénznem Időpecsét Válaszkód Válasz szöveg Engedélyszám Authorizáció típus URL Nyelvkód Történet
URL jelölés CRYPTO MSGT PID TRID UID AMO CUR TS RC RT ANUM AUTH URL LANG HISTORY
Hossz 1 2 7 16 11 Max. 7 3 14 2 0-255 Max. 6 1 Max. 255 2 Max. 255
Típus N N A N A N A N A A A N A A 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 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.
3.1.6 Tranzakció azonosító (TRID) Véletlen szám, amit az ÁRUHÁZ azonosítja a tranzakciót mind az használható, azaz ha egy másik számára sem osztható újra ki, a lehetőségét. Példa: For ($i=1;$i<=16; $i++) { $szam=rand(1,9); $trid.=$szam; }
készít a tranzakció kezdetekor, és a vásárlás befejezéséig ÁRUHÁZ, mind a BANK oldalán. Egy TRID csak egyszer kereskedő lefoglalt egy TRID-et akkor az más kereskedő véletlen szám generátorral elkerülik a foglalt TRID-re futás
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.
[email protected]
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
[email protected]
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 magyar DE német EN angol IT olasz FR francia PL lengyel PT portugál CZ cseh ES spanyol SK szlovák RO román
[email protected]
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 10 11 12-13 20 21 22 30 50 52 55 56 57
Jelentés A vásárló megérkezett a fizetőoldalra A vásárló engedélyezte a tranzakciót A vásároló nem engedélyezte a tranzakciót Authorizáció folyamatban Sikeres authorizáció, vásárló visszaküldése a boltba Sikertelen authorizáció, vásárló visszaküldése a boltba Bolt megerősítette a terhelést, tranzakció vége Time-out miatt reverzálás szükséges A tranzakció reverzálása kijelölésre került Reverzálás indítása Sikeres reverzálás 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 0 10 20 30 40 50 60 99 3.2
Jelentés A tranzakció még nem lett authorizálva Tranzakció authorizálva Tranzakció megbízás által terhelve (lásd MSGT 76) Tranzakció automatikusan terhelt Tranzakció terhelése visszavonva (lásd MSGT 74) Tranzakció terhelés után visszautalva (lásd MSGT 78) Tranzakció lezárva Hibás kérés
Az egyes üzenetek struktúrája
3.2.1 (2. lépés) Fizetési tranzakció inicializálása (ÁRUHÁZ→BANK, MSGT=10) Mező neve URL jelölés Üzenettípus MSGT
[email protected]
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 URL jelölés Üzenettípus MSGT Bolt ID PID Tranzakció azonosító TRID Válaszkód RC 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 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 URL jelölés Üzenettípus MSGT Bolt ID PID Tranazakció azonosító 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) Mező neve Üzenettípus Bolt ID Tranzakció azonosító
URL jelölés MSGT PID TRID
MSGT értéke 21. 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
[email protected]
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
URL jelölés MSGT PID TRID RC RT ANUM AMO
MSGT értéke 31. RC értékei: 00: Sikeres tranzakció bármi más: Sikertelen tranzakció 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) Mező neve Üzenettípus Bolt ID
[email protected]
URL jelölés MSGT PID 16. oldal
Tranzakció azonosító Bolt által ismert összeg
TRID 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
URL jelölés MSGT PID TRID HISTORY RC
MSGT értéke 38. RC értékei: 00: Sikeres lekérdezés 01: Sikertelen lekérdezés 3.2.10 A Tranzakcó adatainak/állapotának lekérdezése, visszautalás kezdeményezése (ÁRUHÁZ-BANK, MSGT=70) Paraméter PID TRID MSGT AMO
Hossz 7 16 2 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 PID TRID MSGT RC AMO Status
Hossz 7 16 2 2 Max 7 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
[email protected]
17. oldal
3.2.11 Még nem terhelt tranzakciók visszavonása (ÁRUHÁZ-BANK, MSGT=74) Paraméter PID TRID MSGT AMO
Hossz 7 16 2 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 PID TRID MSGT AMO Status
Hossz 7 16 2 Max 7 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 PID TRID MSGT AMO
Hossz 7 16 2 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 PID
[email protected]
Hossz 7 18. oldal
TRID MSGT AMO RC RT
16 2 Max 7 2 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 BANK,MSGT=80)
zárás)
után,
Paraméter PID TRID MSGT AMOORIG AMONEW
visszautalandó
összeg
beállítása
(ÁRUHÁZ-
Hossz 7 16 2 Max 7 Max 7
MSGT értéke 78. AMOORIG: eredeti összeg (alapértelmezetten a terhelt összeg) AMONEW: új visszautalandó összeg (0
Hossz 7 16 2 Max 7 2
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 [email protected]
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: [email protected]
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:
[email protected]
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=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
minden esetben 1 lesz, a titkosító modul automatikusan beállítja
MSGT=10
Az üzenetek kódja
PID=0001
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ó
[email protected]
22. oldal
kulcsot használni (tikosításról bővebben 4.3 fejezetben ). TRID=5718203720023838
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
UID=BBBABCDEFGH
CUR=HUF
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!
TS=20081018113054
A tranzakció időpecsétje. Formátuma: EEEEHHNNOOPPMM,
AUTH=0
Minden esetben 0
LANG=HU
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 magyar DE német EN angol IT olasz FR francia PL lengyel PT portugál CZ Cseh ES Spanyol RO Román SK Szlovák
URL=www.valaszurl.hu/val asz.html
Á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).
AMO=10
[email protected]
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 file-okat az eljárást, ehhez másoljuk egy könyvtárba a következő 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ó): .des .reg sakiCrypt.dll sakide.exe
//kulcsfile adatai c:\teszt>sakide -i -m Key ID: Key path: ./ Key size: 38 ID (internal): EKI Version: 2 Market ID (internal): 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=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=0001&CRYPTO=1&DATA=1Cp4Uo3%2BXGkA7jvB2x98543umpgus 6hZ1LzrVmZpv3DL0SLDWA881oL2kW595PNDflgxM%2FzxXnZf31pyg07LbekkCSgI Rbjc6vU9vszdF9KM%2FyjgRaSGSB%2F9SVsAb7jgF3nVSceR41CrIjoAIqwvKsBtP9 WNNtASWdTM2YNuB6EntsamhKft6AyM6i909nIyH6iXpKhwd7zYHqJlMRSomAIC" //eredmény PID=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ó! 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); [email protected]
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.
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
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 [email protected]
28. oldal
000001&LANG=HU&TS=19700108000006&AUTH=0&AMO=10000&URL=http://localhost/"; echo "Cleartext: ".$cleartext."
"; $crypto=ekiEncodeUrl($cleartext,"CIB.des"); echo "Crypted: ".$crypto."
"; $cleartext2=ekiDecodeUrl($crypto,"CIB.des"); echo "Cleartext: ".$cleartext2."
"; */ ?> 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>24)&0xff); binData[i++]=(byte)((c>>16)&0xff); binData[i++]=(byte)((c>>8)&0xff); binData[i++]=(byte)(c&0xff); byte padding=(byte)(len(s.length()+4)); for(; i
29. oldal
Cipher aes = Cipher.getInstance("DESede/CBC/NoPadding"); aes.init(Cipher.ENCRYPT_MODE, desKey, ivVector); byte[] cipherText=aes.doFinal(binData); // A hossz/8 ertek 3-ra oszthatora kibovites. Ez nincs a doksiban, de igy mukodik. int ct3Len=(cipherText.length/8)%3; if(ct3Len==0) ct3Len=3; byte[] cipherText3=new byte[cipherText.length+ct3Len]; for(i=0; i
/** Kifejtés */ public String decode(String data){ try { data=URLDecoder.decode(data,"UTF-8"); byte[] encPadded=Base64.decode(data); // Kodolt adat padding-elve mod3-ra. int len=encPadded.length; len=len-encPadded[len1]; // Padding leszedese byte[] enc=new byte[len]; for(int i=0; i
[email protected]
30. oldal
DESedeKeySpec keyspec = new DESedeKeySpec(binKey); SecretKeyFactory keyfactory = SecretKeyFactory.getInstance("DESede"); SecretKey desKey = keyfactory.generateSecret(keyspec); IvParameterSpec ivVector = new IvParameterSpec(iv); Cipher aes = Cipher.getInstance("DESede/CBC/NoPadding"); aes.init(Cipher.DECRYPT_MODE, desKey, ivVector); byte[] clearText=aes.doFinal(enc); // Dekodolt adat len=clearText.length; len-=clearText[len-1]+4; // Padding, CRC leszedese char tmp[]=new char[len]; for(int i=0; i$trid
"; print "Titkosítás:
";
$parancs = '/valami/sakide.static -v -s "MSGT=10&PID=0001&TRID="123321123321" &UID=12345678&AMO=3600&CUR=HUF&TS='.$ts.'&AUTH=0 &LANG=HU&URL=http://valami.hu/index.php"'; print $parancs."
"; $str = exec($parancs, $output, $return_var); print "sakide kódolt sztringje:
"; print $str; print "
"; print "sakide visszatérési értéke:
"; print $return_var; print "
"; print "Bank meghívása és visszatérése:
"; [email protected]
31. oldal
print "http://ekit.cib.hu:8090/market.saki?".$str."
"; $content = getresp("http://ekit.cib.hu:8090/market.saki?","$str",$trid,0); print $content; print "
"; $parancs = 'sakide.static -d -s "'.$content.'"'; print "Dekodolás:
"; print exec($parancs, $output, $return_var); print "Dekodólt érték:
"; print $return_var; A BANK és az ÁRUHÁZ közötti kommunikációnak a fenti kódolás az alapja. A dokumentációban leírt üzeneteket e metódus alapján kell beküldeni. Ettől eltér a 20-as üzenet ami a vásárló átirányítását jelenti a fizetőoldalunkra. 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). echo "<meta http-equiv='Refresh' content='5;URL=https://ekit.cib.hu/customer.saki?$str_encoded20'>"; Az $str_encode tartalmazza a kódolt 20–as üzenetet ami a következőket tartalmazza. MSGT=20
Üzentet kódja
TRID=5515725650636029
A 10-es üzenetben megadott TRID
PID=
Boltazonosító
[email protected]
32. oldal
4.3.4 Fizetőoldali lépések folyamata 1. Kártyaadatok megadása
2. Jóváhagyás
3. Valós idejű authorizáció és átirányítás
[email protected]
33. oldal
A BANK egy HTML oldalt helyez 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 standard esetben ezen a ponton van utoljára lehetősége). A VÁSÁRLÓ kitölti a fizetőoldal mezőit, visszaküldi a BANK-nak, amely, ha a tranzakciót engedélyezték, megkezdi annak végrehajtását. Ha a VÁSÁRLÓ a BANK–nál a tranzakció megkezdését, 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 Internettől függetlenül. Amennyiben a VÁSÁRLÓ a tranzakció megszakítását kérte, a BANK bejegyzi a megszakítást, és nem authorizál. A BANK a VÁSÁRLÓ-t számára transzparens módon visszaküldi az ÁRUHÁZ-ba, természetesen 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. Fentiek megtörténtét követően az ÁRUHÁZ újra felveszi a kapcsolatot a BANK-kal, és elkéri a tranzakció azonosítóhoz tartozó authorizációs eredményt. Erre a kérésre szolgál a 32-es üzenet, mely válaszában RC és RT paraméterei egyértelműen mutatják a tranzakció eredményét: MSGT=32 TRID=5515725650636029 PID= AMO
Üzentet kódja A 10-es üzenetben megadott TRID Boltazonosító Eredeti összeg
4.3.5 Time-out miatti reverzálási folyamat leírása: Nagyon fontos, hogy a 10 üzenet és a 32-es üzenet között maximum 10 perc telhet el! Ez azt jelenti, hogy amennyiben a BANK 10 percen belül nem kapja meg a megfelelő 32-es üzenetet, a tranzakciót automatikusan reverzálja (visszafordítja) a kártyát kibocsátó banknál. Az ÁRUHÁZ is köteles ebben az esetben értesítést küldeni az ügyfélnek, mely szerint a VÁSÁRLÁS nem sikerült. Mivel a legtöbb esetben ez azért fordul elő, mert a vásárlónak megszakad a kapcsolata a bankkal, a tranzakció lezárásáról az áruháznak e-mailt kell küldeni a vásárló részére a tranzakció lezárásáról! Ha a kapcsolat a protokoll bármely pontján megszakad (pl. a VÁSÁRLÓ bontja a vonalat, URL-t vált, vonalszakadás a BANK és ÁRUHÁZ között), a BANK-ban a tranzakció time-out-tal végződik. A time-out ideje a BANK-ban 10 perc, de ezt az időtartamot, mást mutató tapasztalatok alapján változtathatóra kell programozni. A vezérlés a BANK-ból nem kerül vissza az ÁRUHÁZ-hoz. Ha a BANK számára nem egyértelmű, hogy a tranzakció sikertelen lett, a time-out után a BANK ún. reverzált indít, majd lezárja a tranzakciót, és annak adatai többé nem lesznek elérhetőek az ÁRUHÁZ számára. Ilyenkor az ÁRUHÁZ-ban a tranzakciónak szintén time-out-tal kell végződnie. Tehát egy tranzakció csak akkor tekinthető befejezettnek, ha minden lépése lezajlott (utolsó az MSGT=31). A tranzakció állapotát mindkét félnek (BANK és ÁRUHÁZ) követnie kell ahhoz, hogy mindkettő biztonsággal meg tudja állapítani, hogy egy tranzakció éppen milyen fázisban van, és hogy a megadott időtartam nem telt-e le. Ha a tranzakció bármely fázisában time-out-ra fut, akkor a BANK kötelessége, hogy az esetleges sikeres authorizációt reverzálja, a tranzakciót sikertelenként lezárja, az ÁRUHÁZ feladata pedig a megrendelés törlése, valamint a tranzakció ÁRUHÁZ oldali nyilvántartásának lezárása.
[email protected]
34. oldal
Time out-ra futás esetén is le kell zárnia a webáruháznak az adott tranzakciót – MSGT=32-vel. Banki választ csak a böngésző ún. content-jéből van lehetőség kiolvasni, mert ebben az egy esetben az MSGT=31 válasz hiányzik. Csak és kizárólag ebben az egy esetben a tranzakció webáruház általi lezárása UTÁN kell az MSGT=33-as információt kérő üzenettel lekérdezni a banki oldalról az adott tranzakciót. Ekkor már lesz banki válasz.(MSGT=31). Félreértésre adhat okot, hogy a vásárló ebben az esetben is kap a foglalásról SMS-t bankjától, de a visszafordításról külön értesítést általában nem kap, (kibocsátó banktól függő) ezt csak a számlatörténetében követheti nyomon. Az ÁRUHÁZ a 37-es üzent segítségével győződhet meg arról, hogy mi történt a tranzakcióval. MSGT=37 TRID=5515725650636029 PID= AMO
Üzentet kódja A 10-es üzenetben megadott TRID Boltazonosító Eredeti összeg
HISTORY mező tartalmazza a lekérdezés pillanatáig bekövetkezett összes állapotot, egymástól vesszővel elválasztva. PL_HISTORY=10,11,20,21,30 (sikeresen lezárt fizetés) A következő táblázat tartalmazza a lehetséges válaszokat: Kód és annak jelentése: 10 11 12 - 13 20 21 22 30 50 52 55 56 57 4.4
A vásárló megérkezett a fizetőoldalra A vásárló engedélyezte a tranzakciót A vásároló nem engedélyezte a tranzakciót Authorizáció folyamatban Sikeres authorizáció, vásárló visszaküldése a boltba Sikertelen authorizáció, vásárló visszaküldése a boltba Bolt megerősítette a terhelést, tranzakció vége Time-out miatt reverzálás szükséges A tranzakció reverzálás kijelölésre került Reverzálás indítása Sikeres reverzálás Sikertelen reverzálás
Forinttól és eurótól eltérő devizanemben feltüntetett árakról
A BANK az adott tranzakcióra az inicializált devizanemtől függően forintban vagy euróban kér engedélyt (a kártyabirtokos számláján a választott devizanemben látszik a tranzakcióra vonatkozó engedélykérés). A BANK a tranzakciókat a választott devizanemben küldi meg elszámolásra a kártyatársasághoz, konverziót nem végez. A tranzakciókat a kártyatársaság saját árfolyamán konvertálja arra a devizára, amelyben a kártyakibocsátó bankkal elszámol. A kártyakibocsátó bank a beérkezett devizában terhelt összeget átváltja a kártyabirtokos számlájának devizanemére. Mindehhez hozzájárul, hogy a tranzakció és a terhelés között eltelik pár nap, így előre nem is lehet kalkulálni az árfolyammal, mert nem lehet tudni, hogy a terhelés napján milyen árfolyam lesz érvényben. A jelenleg hatályban levő 1997. évi fogyasztóvédelemről szóló törvény 14. szakasza alapján a fizetendő összeget az ÁRUHÁZ honlapján kötelező feltűntetni a hazai törvényes fizetőeszközben
[email protected]
35. oldal
is, azaz forintban, attól függetlenül, hogy tájékoztató jelleggel, más devizanemben is meg kívánja jeleníteni a termék/szolgáltatás árát. A törvényi kötelezettség és vásárlói tájékoztatás fontossága, hogy forinttól és eurótól eltérő devizanemben megjelenített fizetendő összeg esetén (pl.: USD) az összeg csak tájékoztató jelleggel van feltűntetve, ezért a következő tájékoztató szöveg feltűntetését várja el a BANK az ÁRUHÁZ oldalán: Tájékoztatjuk vásárlóinkat, hogy a <ÁRUHÁZ neve> honlapon a kártyás fizetés során történik a tranzakció, függetlenül attól, hogy a kártyabirtokos kártyája nem forint/euró devizanemű. Az oldalon látható <devizanem> (pl.: USD) árfolyamokat csupán tájékoztató jelleggel közöljük, a CIB Bank deviza eladási árfolyama szerint. Az Ön bankszámla kivonatán megjelenő, számlavezetési devizában beterhelt tételben látható összeg – a kártyatársasági, illetve a kibocsátó banki konverziók miatt – minimálisan eltérhet az árfolyamváltozás következtében. We kindly inform our customers that <ÁRUHÁZ neve> the bankcard payments are processed in HUF/EUR. This applies to transactions made with an international card as well. For information, we indicate the CIB Bank’s daily foreign currency sell rate in <devizanem>, but the counter-value of the transaction will always be debited in HUF/EUR. Please be aware that - due to the varying exchange rates - the actual price for your purchase on your bankcard statement can be slightly higher or lower then stated in the order value. A BANK lehetőséget biztosít az ÁRUHÁZ számára, hogy tájékoztató jelleggel felhasználja a CIB Bank Zrt. árfolyamait a következő RSS csatornáról. http://www.cib.hu/%5Erss/devarf.xml 4.5
Élesítés feltételei
4.5.1 Logók megjelenítése Az ÁRUHÁZ főoldalán szerepelnie kell az a BANK által nyújtott csomagban található elfogadott kártyák logóinak (VISA, VISA Electron, MasterCard és Maestro) a CIB Bank Zrt. logójának és a fizetésről szóló vásárlói tájékoztatónak. A. CIB Bank és kártyatársasági logók: A „Logó” könyvtárban megtalálhatóak a CIB és kártyalogók külön-külön filenéven, valamint 30 pixel, 50 pixel és 85 pixel magasságú méretekben egybe szerkesztve. Megjelenítésre vonatkozó irányelvek: Az ÁRUHÁZ állandóan látható részén szükséges megjeleníteni Javaslat: fejlécen, bal oldali menüsor alján, lábléc bal vagy jobb oldalán Bank logóhoz szövegi kíséret: „Kártyás fizetés szolgáltatója:” Kártyalogókhoz szövegi kíséret: „Elfogadott kártyák” Bank és kártyalogókhoz link készítése, amely a fizetésről szóló vásárlói tájékoztatóra hivatkozik. A linkhez buborék szöveg készítése (alt szöveg) a logóhoz tartozó szövegi kísérettel, ahol az külön nem kerül megjelenítésre A logók nem szerepelhetnek transzparensen a háttér előtt Logók további átméretezése engedélyezett a jól láthatóság mértékéig
[email protected]
36. oldal
VeriSign logó nem jeleníthető meg a kereskedő oldalán a kártyás fizetéshez kapcsolódóan, csak abban az esetben, ha maga az ÁRUHÁZ rendelkezik a tanusítvánnyal. B. Fizetésről szóló vásárlói tájékoztató: Megjelenítésre vonatkozó irányelvek: A Bank és kártyalogókról linkelve jelenjen meg Főoldali menüsoron vagy „Súgó”, „Vásárlói tájékoztató”, „Vásárlási feltételek”, „Fizetési módok” vagy „Bankkártyás fizetés” menükben Belső, HTML-ben készített oldalon kerüljön (pop-up mellőzése javasolt) Sárga kiemeléssel jelölt szövegek (Webáruház, áru/szolgáltatás) helyettesíthetők az ÁRUHÁZ nevével és értékesített termék és szolgáltatás nevével. Az alábbi illusztráción a logók helyes megjelenítési formájukban és lehetséges elhelyezésben láthatók:
4.5.2 ÁRUHÁZ működésre vonatkozó követelményei A banki tesztelés során kizárólag a banki fizetési tranzakció létrejöttének technikai feltételei nem elégítik ki az élesítés feltételeit. A BANK minden esetben az egész ÁRUHÁZ-at teszteli, beleértve a megrendelés egyes lépéseit is, úgymint a regisztráció, termékválasztás folyamatát is. A. Tranzakció eredményének visszaigazolása képernyőn és e-mail-ben [email protected]
37. oldal
Miután megtörtént a BANK fizetőoldalán a fizetés, a vásárló visszakerül az ÁRUHÁZ-ba és az összefoglaló táblázatban a következő paraméterek feltüntetése kötelező: Válaszkód (RC): Két számból álló válaszkód. Válaszüzenet (RT): RC-hez változó hosszúságú szöveg 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. Tranzakció azonosító (TRID): 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. 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 ANUM mező kitöltöttsége nem jelenti automatikusan az authorizáció sikerességét! Lásd 4.3.5. Fizetett összeg (AMO): A vásárló által fizetett összeg abban az esetben, ha a tranzakció sikeres volt (RC=00). B. Megrendelés és fizetés adatainak összekapcsolhatósága, visszakereshetősége Az ÁRUHÁZ köteles regisztrálni a VÁSÁRLÓ személyes/megrendelésre vonatkozó adatait, valamint rögzíteni a tranzakcióra vonatkozó adatokat. Előírás, hogy az ÁRUHÁZ adminisztrációs / megrendeléskövető rendszerében a tranzakciós adatok összekapcsolhatók legyenek a VÁSÁRLÓ megrendelésének adataival. Ez azért fontos, mert a banki kereskedői kifizetések analitikán az engedélyszámot (elektronikus kivonaton a tranzakció azonosítót is) jeleníti meg egy vásárláshoz kapcsolódóan, s a számlázáshoz kapcsolódóan az ÁRUHÁZ feladata összekapcsolni ezt adott VÁSÁRLÓ befizetéseivel. A BANK ezt a feltételt a tesztelése során nem kéri bemutatni, azonban e feltétel teljesítése az ÁRUHÁZ érdeke. C. Time-out ÁRUHÁZ oldali lekezelése Ha a tranzakció bármely fázisában time-outra fut, akkor a BANK kötelessége, hogy az esetleges sikeres authorizációt reverzálja, a tranzakciót sikertelenként lezárja, az ÁRUHÁZ feladata pedig a megrendelés törlése, valamint a tranzakció ÁRUHÁZ oldali nyilvántartásának lezárása, s ennek visszaigazoló képernyőn vagy e-mail-ben történő kommunikációja az 1. pont szerint. Az esetek többségében time-outot követően a VÁSÁRLÓ nem tér vissza az ÁRUHÁZ oldalára, ezért e-mailben történő visszaigazolás kötelező. D. Banki fizetőoldalon megjelenített ÁRUHÁZ elnevezésének ellenőrzése Az ÁRUHÁZ vagy a kártyaelfogadóhely cégneve megjelenítésre kerül a banki fizetőoldalon. Ennek elnevezésre alapértelmezettként a Kártyaelfogadói szerződésben megadott honlapcím. Amennyiben ettől eltérőt kér az ÁRUHÁZ, élesítést megelőzően lehetséges jelezni szándékát. E. ÁRUHÁZ logó elhelyezése fizetőoldalon Az ÁRUHÁZ-nak lehetősége van a saját logót elhelyezni a fizetőoldal fejlécében ( kötötten 788 pixel szélességű, választhatóan legfeljebb 150 pixel magasságú jpeg file-ban.), egyéb módosítás nem engedélyezett. Alábbi ábra narancssárga színnel jelöltük azt a helyet, ahová az ÁRUHÁZ képet helyezhet el.
[email protected]
38. oldal
Amennyiben az ÁRUHÁZ nem él az egyéni stílus alkalmazásával (melyre bármikor igényt tarthat, illetve bármikor lemondhat róla), a képen narancssárga színnel jelölt mező nem lesz látható. F. Sikertelen fizetés esetén újrafizetés lehetőségének biztosítása A fizetés bármely okból történő sikertelensége esetén biztosítani kell a fizetés újrakezdésének lehetőségét, ami azt jelenti, hogy a tranzakció visszaigazoló oldalánál javaslunk biztosítani egy „Fizetés újra” gombot, melynek segítségével a fizetés újra megkísérelhető. Ezt a javaslatot a VÁSÁRLÓ érdekeit figyelembe véve tesszük. Javasoljuk továbbá az általános szerződési feltételekben kiemelni, amennyiben a vásárló a kosarába helyezett terméke(ke)t adott idő alatt – például 24 órán belül – nem fizeti ki, úgy az(ok) a kosarából törlésre kerül(nek). Élesítési kritériumoknak történő megfelelés önellenőrzéséhez az 1-es számú mellékletben található lista segítséget nyújt. G. Felhasználói azonosító (UID paraméter) kötelező kitöltése 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.
H. Az áruház kereskedőjére vonatkozó információk A kereskedő elérhetőségét a honlapon közölni kell. Erre szolgálhat a Rólunk, Impresszum, vagy Elérhetőség linkek, melyeknek tartalmaznia kell a kereskedővel kapcsolatos adatokat: Név, telephely pontos címe, telefonszám, e-mail cím, webáruház, illetve cégadatok, úgy mint adószám, bankszálmaszám, stb. 4.6
Élesítési kérés
Amikor elkészült a végleges fizetési kapcsolat, e-mail-ben kell jelezni az élesítési szándékot. Az e-mailnek a következő információkat kell tartalmaznia: PID A tesztelhető alkalmazás URL-je Ha jelszóvédett, akkor usernév/jelszó, vagy leírás a regisztráció menetéről Rövid leírás a vásárlás menetéről [email protected]
39. oldal
Éles üzemű honlap IP címének megadása Mielőtt a BANK az éles kulcsot kiadná, le kell tesztelnie az ÁRUHÁZ oldalát, és a banki kapcsolatot. A tesztelés eredményéről az áruház e-mailben kap visszajelzést. Az e-mail tartalmazza a tesztelés során észrevett hibákat. 4.7
Élesítés
Amennyiben a banki teszt sikeresen lezárul, elindul az élesítési folyamat. Ennek befejezése után a bank e-mailben elküldi a fejlesztőnek az éles kulcsokat, zip 2.0 compatible encryption módszerrel 22 karakteres jelszóval titkosított zip file-ban. A jelszót a számlavezető fiókban a kártyaelfogadói szerződést aláíró képviselője vagy meghatalmazottja veheti át. Amennyiben másik fiókban szeretné átvenni az elismervényt, ezt az [email protected] címre küldött levélben kérjük jelezni.
[email protected]
40. oldal
5.
VISSZAUTALÁS FOLYAMATA
Lehetőség van arra, hogy a vásárló részére akár a teljes, akár a terhelésnek csak egy bizonyos részét utaljuk vissza, erre a tranzakciót követően 180 nap áll rendelkezésre. Fontos megjegyezni, hogy a visszautalás kezdeményezése elött be kell állítani a visszautalandó összeget, még akkor is, ha teljes összeget szeretnénk visszautalni. Továbbá egy tranzakcióra csak egyszer lehetséges visszautalást indítani, ezután a tranzakció státusza változik, mely után már nem fogad a rendszer visszautalási kérést. A visszautalás minimális összege: 100 HUF / 1 EUR. Egyedi esetben az ÁRUHÁZ a visszautalást e-mailben is kérhetik az [email protected] címre küldött levélben, melynek tartalmaznia kell a következőket: 5.1
PID, TRID, AMO, ANUM, TIMESTAMP és a visszautalandó összeg
Visszautalás lépései:
A visszautalás előfeltétele, hogy a tranzakció státuszát ellenőrizzük. Erre a 70-es üzenetet használjuk: MSGT=70
Üzenet típusa
PID=CIB0001
ÁRUHÁZ azonosító
TRID=1983198319831983
Tranzakció azonosító
AMO=150
Összeg
A visszakapott 71-es üzenet - példa: MSGT=71
Üzenet típusa
PID=CIB0001
ÁRUHÁZ azonosító
TRID=1983198319831983
Tranzakció azonosító
AMO=150
Összeg
RC=00
Válaszkód
RT=Tranzakció elfogadva
Válaszüzenet
CURAMO2=150
A 80-as üzenetben ezt kell beállítani AMOORIG értéknek
STATUS=30
Státuszkód
ANUM=218159
Engedélyszám
Figyelem! A CURAMO2 első visszautalás inicializálása esetén minden esetben 0 értékkel tér vissza. STATUS mező a tranzakció analitikai állapotáról nyújt információt, melyek a következők lehetnek: Kód Jelentés: 0 A tranzakció még nem lett authorizálva 02
Hiba, a visszautalás összege kisebb, mint 100 HUF / 1 EUR
10
Tranzakció authorizálva, banki zárás előtt indítható a visszavonás kérés (74)
30
Tranzakció napi zárást követően automatikusan terhelve (csak 80 és 78)
[email protected]
41. oldal
40
Tranzakció terhelése napi zárás elött visszavonva
50
Tranzakció terhelés után visszautalva
60
Tranzakció lezárva
99
Hibás kérés
Megjegyzés: •
E-mailben kért visszautalás esetén a rendszer keretein belül nem mutat változást a tranzakció státusza.
•
100 HUF / 1 EUR-nál kisebb összeg visszautalását a rendszer nem fogadja el.
•
Amennyiben már volt egyszer sikeres visszautalás, akkor a STATUS=60, vagyis NEM kezdeményezhető még egyszer.
Ezt az üzenettípust bármikor használhatjuk ellenőrzésre is, de visszautalás előtt mindenképpen le kell kérdezni. a. Banki napi feldolgozást megelőző tranzakció visszavonása Ha a STATUS 10-es értéket mutat, visszavonhatjuk a terhelésre vonatkozó megbízást, azonban csak teljes összeget oldhatunk fel. Erre a 74-es üzenetet használjuk: MSGT=74 Üzenet típusa PID=CIB0001
ÁRUHÁZ azonosító
TRID=1983198319831983
Tranzakció azonosító
AMO=150
Összeg
A 70-es üzenettel lekérdezzük a tranzakció státuszát, majd 40-es státuszkódot fogunk kapni, ha a tranzakció lezárult és a feloldást a kártyás rendszer is visszaigazolta, a státuszkód 60-as üzenetre vált. Ez azt jelenti, hogy a vásárló számláján a terhelés feloldásának kezdeményezését elküldte bankunk a kártyakibocsátó bank felé. A kártyabirtokos számláján a terhelés feloldása a kibocsátó bankok saját elszámolási rendje szerint történik. Tranzakció visszavonzásra adott napi zárásig van lehetőség, amely 18:00 időpontban történik. b. Banki napi zárást követő visszautalás A banki zárást követő visszautalás feltétele, hogy a tranzakció terhelve legyen azaz a státuszkódnak 30-as állapotban kell lennie. Tranzakció visszautalására napi feldolgozást követően az alábbiak szerint van lehetőség. A 80-as üzenettípus alkalmas arra, hogy beállítsuk a visszautalandó összeget: MSGT=80 Üzenet típusa PID=CIB0001
ÁRUHÁZ azonosító
TRID=1983198319831983
Tranzakció azonosító
AMOORIG=150
Az AMOORIG összege megegyezik a 70-es üzenet válaszául kapott CURAMO2 értékével,
AMONEW=130
Összeg (Visszautalandó összeg)
Az AMOORIG értéke a 70-es üzenetre kapott válaszban tartalmazott CURAMO2 értéke lesz.
[email protected]
42. oldal
Az AMONEW értéke az az összeg amennyit szeretnénk visszautalni. A fenti példában szereplő paramétereknél 130 Ft fog megjelenni a vásárló számláján jóváírásként. Ezzel beállítottuk a visszautalás összegét. Csak egyszer lehet visszautalást kezdeményezni, függetlenül attól, hogy a visszautalandó összeg kisebb, mint az eredeti összeg!
A következő lépés a visszautalás kezdeményezése 78-as üzenettel. Csak abban az esetben használhatjuk ezt az üzenetet, ha elötte a 80-as üzenettel beállítottuk a visszutalandó összeget. MSGT=78 PID=CIB0001 TRID=1983198319831983 AMO=150
Üzenet típusa ÁRUHÁZ azonosító Tranzakció azonosító Összeg (Eredeti összeg)
AMO értéke itt mindig a 32-es üzenet eredményeképpen kapott összeggel egyezik meg. A 78-as üzenet küldését követően meg kell hívni a 70-es üzenettel a státuszfrissítést, csak ekkor kerül érvényesítésre a visszautalás. A tranzakció összegének jóváírása a VÁSÁRLÓ számláján a kibocsátó bank elszámolási rendjétől függően történik meg. Stuktogram: 70-es üzenet meghívása HA STATUS: =10: 74-es üzenet, tranzakció visszavonása (csak a teljes összegre) 70-es üzenet, státuszfrissítés
=30: 80-as üzenet, (AMOORIG=CURAMO2), AMONEW= visszautalandó összeg) összeg beállítása 70-es üzenet, státuszfrissítés 78-as üzenet, visszautalás indítása 70-es üzenet, státuszfrissítés
Folyamatábra:
[email protected]
43. oldal
Status =10
Terhelés tiltása MSGT= 74
Status=40, banki zárás után Status = 60 A teszten a Status = 60 lesz!
[email protected]
Tr. lekérdezés
70
MSGT
Status=30
MSGT 80, összeg beállítása,
MSGT 78, visszautalás indítása
Status = 50, banki zárás után Status =60
44. oldal
6.
A CIB TITKOSÍTÓ MODULJA
6.1
Az ekiCrypt feladata és használatának feltételei
A BANK a fent leírt titkosítási módszerhez készített egy ekiCrypt nev C library-t, amit az Üzemeltetők rendelkezésére bocsát. A BANK a titkosító modult folyamatosan karbantartja, a felismert hibákat javítja és teszteli. Ez a programmodul képes az adatok jelen dokumentumban leírt módon történt be- és kititkosítására és megfelelő formátumának kezelésére. A lib-hez a BANK továbbá rendelkezésre bocsát egy szintén C nyelven íródott példaprogramot annak forráskódjával együtt: • Az ekiCrypt legutolsó verziószáma 1.0.3. • Jelenleg támogatott platformok: Windows NT, AIX, Linux, Sun Solaris A BANK jelen dokumentációt és a példaprogramot leszámítva a modulhoz külön támogatást nem nyújt, a modul ÁRUHÁZ szoftverhez történő illesztését nem vállalja, és az esetlegesen a modul használatából ered bárminemű kárért semmilyen felelősséget nem vállal. 6.2
Titkosítás specifikációja (ekiEncodeUrl)
INT ekiEncodeUrl (LPSTR inBuffer, INT inBufferSize, LPSTR outBuffer, LPINT outBufferSize, INT cryptoType, LPSTR keyFilePath) Az URL formában megadott üzenetet alapvető ellenőrzéseknek veti alá, URL enkódolja, DES-eli, uuencodolja, és a protokollnak megfelelően URL formába illeszti. A DES kulcsot Win32 alatt a registry-ben vagy file-ban, egyéb rendszereken file-ban tároljuk. Paraméterek: inBuffer: A titkosítandó url-t tartalmazó buffer. InBufferSize: A titkosítandó url hossza. OutBuffer: A titkosított url ebbe a bufferbe fog kerülni. OutBufferSize •Input: A titkosított url részére lefoglalt buffer mérete, minimálisan 4/3 * (inBufferSize + 12). •Output: A titkosított url mérete. CryptoType: A szükséges titkosítás típusa. • 1 - DES KeyFilePath: A titkosító (DES) kulcs file elérési útja, amennyiben a kulcs file-ban tárolódik. NULL, ha a kulcs a registry-ben található (csak Win32). Megjegyzések: 1.
Az inBuffer paramétert a tényleges url stringnél nagyobbra célszerű választani.
2.
Windows NT alatt a DES kulcsot a HKEY_LOCAL_MACHINE\SOFTWARE\CIB\EKI\Keys\<ÁRUHÁZId> registry kulcs bináris típusú “des” nev értékében is lehet tárolni.
3.
A DES kulcs file neve <ÁRUHÁZId>.des ? Az inBuffer-ben lévő url PID mezőjének létező ÁRUHÁZ id-t kell tartalmaznia, és a file-ban tárolt DES kulcsot is e szerint az adat szerint találja meg. (Un*x: case sensitive! )
4.
Ha az URLtartalmaz CRYPTO mezőt, akkor az eljárás kiszedi belőle.
[email protected]
45. oldal
Lehetőséges visszatérési értékek: UER_OK: UER_BADPARM: UER_NOMEM: UER_BADSIZE: UER_NOKEY: UER_BADKEY: 4.1
Ok. Rossz hívási paraméter: inBuffer vagy outBuffer == NULL. Nincs elég memória. Output buffer mérete (outBufferSize) kicsi. Kulcs nem található. Rossz kulcs struktúra.
Visszafejtés az ekiCrypt-el (ekiDecodeUrl)
INT ekiDecodeUrl (LPSTR inBuffer, INT inBufferSize, LPSTR outBuffer, LPINT outBufferSize, LPINT cryptoType, LPSTR keyFilePath); A kódolt, url-formátumú inputból kiolvassa a titkosított adatokat, uudekódolja, ki- DES-eli és ellenőrzéseket végez rajta. Az üzenetet url-enkódolva adja vissza. Paraméterek: inBuffer: InBufferSize: OutBuffer: OutBufferSize •Input:
A titkosított url-t tartalmazó buffer. A titkosított url hossza. A titkosítatlan url ebbe a bufferbe fog kerülni. A titkosítatlan url részére lefoglalt buffer mérete, minimálisan 3/4 * inBufferSize. A titkosítatlan url mérete.
•Output: CryptoType • Ha értéke nem NULL, akkor ebbe a bufferbe kerül a kapott adat titkosításának típusa, és a kititkosított adat nem fogja tartalmazni a Crypto mezőt. • Ha értéke NULL, akkor a kititkosított adatban benne hagyja a Crypto mezőt. KeyFilePath: A titkosító (DES) kulcs file elérési útja, amennyiben a kulcs file-ban tárolódik. NULL, ha a kulcs a registry-ben található (csak Win32).
Megjegyzések: • A DES kulcs file neve <ÁRUHÁZId>.des • Az inBuffer-ben lévő url PID mezőjének létező ÁRUHÁZ id-t kell tartalmaznia. • Ha a CryptoType paraméter értéke NULL, a kititkosított url-ben benne marad a CRYPTO mező. Lehetséges visszatérési értékek: UER_OK: Ok. UER_BADPARM: Rossz hívási paraméter: inBuffer vagy outBuffer == NULL. UER_NOMEM: Nincs elég memória. UER_BADSIZE: Output buffer mérete (outBufferSize) kicsi. UER_NOKEY: Kulcs nem található. UER_BADPAD: Rossz padding, hibás üzenet. UER_CRC: Rossz crc, hibás üzenet UER_BADKEY: Rossz kulcs struktúra. UER_NOFILE: Kulcs file nem található. UER_BADURL: Hibás URL formátum (nem felel meg az EKI specifikációnak) Megjegyzés: Az ekiEncodeUrl az outBuffer-ben visszaadott karakterláncot ellátja a PID, CRYPTO és DATA paraméterekkel. Az ekiDecodeUrl a kapott titkosított adatról levágja ugyanezeket. (Kivéve speciális eseteket, lásd a függvények ismertetését.)
[email protected]
46. oldal
4.2
Kulcs struktúra (TKeyInfo)
typedef struct { char fname[13]; /* filenév */ INT keySize; /*kulcsméret */ char id[4]; /* belső azonosító - elvileg ua. mint marketId*/ unsigned short version; /* verzió */ char marketId[4]; /* áruház azonosítója */ time_t creation_time; /* kulcs elállítási ideje */ } TKeyInfo; 4.3
Kulcsinformációk lekérdezése (ekiGetKeyInfo)
INT EKIAPI ekiGetKeyInfo(TKeyInfo *ekiKeyInfo, char *keyFilePath, char *boltId); A titkosító kulcs adatait adja vissza a TKeyInfo struktúrában. Paraméterek: ekiKeyInfo: keyFilePath: boltId: verziószám:
Kulcs adatai (kimen) Kulcs file helye Áruházazonosító lekérdezése
Lehetséges visszatérési értékek: UER_OK: Ok. UER_NOMEM: Nincs elég memória. UER_BADSIZE: Output buffer mérete (outBufferSize) kicsi. UER_NOKEY: Kulcs nem található. UER_BADKEY: Rossz kulcs struktúra. UER_NOFILE: Kulcs file nem található. 4.4
Verziószám lekérdezése (ekiGetLibVersion)
INT EKIAPI ekiGetLibVersion(char *outBuffer, LPINT outBufferSize); A titkosító modul verziószámának lekérdezése. Paraméterek: outBuffer: outBufferSize:
Ide írja a verziószámot x.y.z formában, \0-val lezárva. outBuffer mérete byte-okban, a lezáró nullának is helyet hagyva.
Lehetséges visszatérési értékek: UER_OK: Ok. UER_NOMEM: Nincs elég memória. UER_BADSIZE: Output buffer mérete (outBufferSize) kicsi.
[email protected]
47. oldal
5.
HIBALEHETŐSÉGEK, JAVASLATOK A BANK-ból jövő adatokat kititkosítás előtt tilos URL dekódolásnak alávetni. A beérkezett adatot először az ekiDecodeUrl-nek átadva ki kell titkosítani, majd az így kapott adatot kell URL dekódolni. Néhány webszervernél elfordulhat, hogy a [9] lépésben kapott 21-es típusú üzenet már URL dekódolva adódik át a szerver oldali programnak. Ennél a lépésnél erősen ajánlott, hogy a kapott paraméterek feldolgozás előtt mindenképpen URL enkódoláson “essenek át”. Az ÁRUHÁZ szoftvere ne függjön a 3.1 fejezetben megadott üzenettípusok adatinak sorrendjétől. Ez a sorrend nem garantált. Az ÁRUHÁZ szoftvere ellenőrizze a 31-es üzenettípusban kapott AMO mezőt, ez az az összeg, amit a vevő ténylegesen kifizetett (sikeres authorizáció esetén). Ha ez nem egyezik az ÁRUHÁZ nyilvántartásával, a tranzakciót ne fogadja el, a megrendelt árut ne szállítsa ki. Ilyenkor a BANK-kal kell felvenni a kapcsolatot, és a tranzakciót meg kell reklamálni. EUR-ban inicializált tranzakció hibaágra fut RC=01 hibakóddal. Ez akkor fordulhat elő, ha nem az adott devizanemhez rendelt PID-et hívja meg az ÁRUHÁZ. EUR devizanemű tranzakcióhoz tartozó PID 1-es számmal kezdődik (pl.: ABC1001). EUR tranzakció esetén AMO értéknél a tizedesvessző alkalmazása és egy tizedesjegyig történő kitöltés RC=01 hibaüzenetet generál (pl.: 10,2). Tizedespontot és két tizedesjegyet kell alkalmazni. 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. A fenti probléma kikerülhet, ha az ÁRUHÁZ nem engedi, hogy a vásárló megváltoztassa egy olyan “kosár” tartalmát, melyhez tartozó tranzakció a BANK felé már el lett indítva. Ha a vásárló még valamit kiválaszt az áruházban, egy “új” kosár nyitható neki, melynek összegére a BANK-tól újabb tranzakció kérhető. Ez a megoldás a VÁSÁRLÓ elől szinte teljesen elfedhet, anélkül, hogy tudná, hogy ténylegesen több kosárral sétál az ÁRUHÁZban. Az ÁRUHÁZ-BANK és a VÁSÁRLÓ-BANK kapcsolat nem ugyanazon az URL-en keresztül jön létre, tehát az ÁRUHÁZ szoftvernek két különböző URL-t kell tudnia kezelni: egy, amin kommunikál a BANK-al, a másikra pedig ahova a vásárlót küldi. Ha a kapcsolat a protokoll bármely pontján megszakad (pl. a VÁSÁRLÓ bontja a vonalat, URL-t vált, vonalszakadás a BANK és ÁRUHÁZ között), a BANK-ban a tranzakció timeouttal végződik. A time-out ideje a BANK-ban 10 perc, de ezt az időtartamot, mást mutató tapasztalatok alapján változtathatóra kell programozni az ÁRUHÁZ-nak. A vezérlés a BANK-ból nem kerül vissza az ÁRUHÁZ-hoz. Ha a BANK számára nem egyértelmű, hogy a tranzakció sikertelen lett, a time-out után a BANK ún. reverzált indít, majd lezárja a tranzakciót, és annak adatai többé nem elérhetek a partnerek számára. Ilyenkor az ÁRUHÁZ-ban a tranzakciónak szintén time-outtal kell végződnie. Tehát egy tranzakció csak akkor tekinthető befejezettnek, ha minden lépése lezajlott (utolsó az MSGT=31). A tranzakció állapotát mindkét félnek (BANK és ÁRUHÁZ) követnie kell ahhoz, hogy mindkettő biztonsággal meg tudja állapítani, hogy egy tranzakció éppen milyen fázisban van, és hogy a megadott időtartam nem telt-e le. Ha a tranzakció bármely fázisában time-
[email protected]
48. oldal
outra fut, akkor a BANK kötelessége, hogy az esetleges sikeres authorizációt reverzálja, a tranzakciót sikertelenként lezárja, az ÁRUHÁZ feladata pedig a megrendelés törlése, valamint a tranzakció ÁRUHÁZ oldali nyilvántartásának lezárása. Fontos, hogy az áruház a tranzakciók minden lépését naplózza, hogy mind a BANK-i, mind az ÁRUHÁZ-i oldalon bármikor visszakereshető legyen, hogy egy tranzakció milyen lépéseken át jutott végállapotba! Nem kell naplózni az MSGT=10 két paraméterét: Auth és URL. Az ÁRUHÁZ a VÁSÁRLÓ-t minden esetben a dokumentációnak megfelelő módon irányítsa át a BANK-ba. Frameset-ek használata erre az esetre tilos, mivel a böngészők egy része az oldal biztonsági szintjét az összes megjelenített oldal függvényében határozza meg. Ez pedig azt eredményezheti, hogy a fizetőoldal a VÁSÁRLÓ böngészőjében nem biztonságos. A fizetőoldal elhagyása után a VÁSÁRLÓ visszakerül az ÁRUHÁZ-ba, melynek biztonsági szintje általában kisebb, mint a fizetőoldalé. Ezt a böngészők egy figyelmeztető üzenettel közlik. Mivel ez félreértésekre adhat okot (az ÁRUHÁZ oldalának megjelenése előtt bukkan fel az üzenet, így a VÁSÁRLÓ azt hiheti, hogy a fizetőoldal nem biztonságos). A fizetőoldalon a “Fizetés” gomb megnyomása után egy magyarázó szöveg jelenik meg, az ÁRUHÁZ kérésére és felelősségére ez elhagyható. A VÁSÁRLÓ fizetőoldalról ÁRUHÁZ oldalára történő visszaküldését követően a fizetés visszaigazolása során a tranzakció azonosító (TRID), engedélyszám (ANUM), időpont, összeg (AMO), Válaszkód (RC), Válaszüzenet (RT) mezők megjelenítése kötelező. Az ÁRUHÁZ oldalon kötelező megjeleníteni a dokumentáció mellékleteként küldött banki biztonsági tájékoztatóját (eCom_CIB.fiz.taj_xx.doc), valamint a „Logo” könyvtárban található CIB Bank, Visa, Verified by Visa, MasterCard, Maestro és Mastercard_Securecode logókat. Javasolt elhelyezések: CIB Bank logó: főoldal lábléc vagy menüsor alatt vagy a vásárlói tájékoztatóban Kártyatársasági logók: főoldal lábléc vagy fizetési mód kiválasztásánál Fizetésről szóló tájékoztató: „Vásárlói tájékoztató” vagy „Fizetési feltételek” vagy Súgó” vagy főoldalon vagy „Bankkártyás fizetés” elnevezésű menükben. Tesztkörnyezetben történő fejlesztői teszteléshez az alábbi válaszkódokat lehet a tesztrendszeren generálni: Fizetőoldalról visszalépés C2 hibát generál, szándékosan hibásan generált fizetéshez ezt a kártyaszámot lehet alkalmazni: 4999 9999 9999 9999, lejárat jövőbeli, CVC nem kell. Ez utóbbira 09-es lesz a hibakód. Sikeres tranzakció elvégzéséhez bármilyen más fentitől eltérő 4-gyel vagy 5-tel kezdődő fiktív kártyaszám és bármely jövőbeli lejárat használható, melynek alkalmazásával 00, tehát sikeres tranzakciót szimulál a rendszer.
[email protected]
49. oldal
8.
VÁLTOZÁSKÖVETÉS
v.1.34a Fizetőoldal és tesztelési folyamatváltozások v.1.35a Új üzenettípus (monitor): 80 v 1.40 Fizetési folyamatának részletes leírása ÁRUHÁZ működésre vonatkozó követelményei Time-out miatti reverzálási folyamat leírása JAVA nyelven történő titkosítási kódrészlet: PHP nyelven (>PHP4) történő titkosítási kódrészlet: SAKIDE programmal történő kódolás v 1.41 Visszautalás / részvisszautalás megvalósítása Hibalehetőségek, javaslatok Segédletek az élesítés követelményeihez v 1.42 EUR tranzakciók kezelése Árfolyam lekérdezése, rss segítségével, XML csatorna címváltozás Visszautalási segédlet v 1.43 Román, szlovák nyelvű fizetőoldalak és tájékoztatók bevezetése (3.1.16-os fejezet) v 1.44 Folyamatábra a fizetési eljárásról (3.sz. Melléklet) v 1.45 A UID használata az MSGT=10 üzenetben (3.1.7-es fejezet) Kereskedő adatai. (4.5.2-es fejezet) A vásárló kötelező tájékoztatása a webáruházban és e-mail-ben Az időtúllépés lekezelése Maestro és MasterCard SecureCode logók
[email protected]
50. oldal
9.
ELÉRHETŐSÉGEK
Név Telefon E-mail Technikai +36-1-399-8998 [email protected] Call Center Banki lásd: www.cib.hu, lásd: www.cib.hu, üzletkötő fióklista fióklista Fejlesztői [email protected] segédlet
[email protected]
Elérhetőség Terület Munkanapokon (hétfőtől Hibabejelentés péntekig): 7-19 óráig Banki nyitvatartási Szerződések, időben számlaügyek Banki nyitvatartási Technikai segítség időben fejlesztés/tesztelés idején
51. oldal
1. SZ. MELLÉKLET Önellenőrző lista élesítés feltételeinek megfelelésére I. KÖTELEZŐ ELEMEK
Bankkártyás fizetési tájékoztató megjelenítése Részletek: • Helye: „Súgó” vagy „Vásárlói tájékoztató” vagy „Fizetési feltételek” menüpontokban, vagy önállóan megjelenítve „Bankkártyás fizetés” menüpontban – ezek az eCom_CIB-fiz.taj_GYFK_hu.doc és az eCom_CIB-fiz.taj_u.doc állományok tartalma. HTML-be kérjük konvertálni. • Elérés: „Vásárlói tájékoztató” mappa
Kártyatársasági- és banki logó feltűntetése Részletek: • Helye: főoldal lábléc vagy oldalsó menüsor alatt vagy vásárlói tájékoztatóban • Javasolt kísérő szöveg banki logóra: „Bankkártyás fizetési szolgáltató: CIB Bank Zrt.” • Javasolt kísérő szöveg kártya logóra: „Elfogadott kártyák:” • Elérés: „Logo” mappa • Átméretezhetőség: engedélyezett a jól láthatóság mértékéig
Visszaigazolás képernyőn kötelező tranzakciós adatokkal Részletek: • Sikeres fizetés megjelenítendő adatai: tranzakció azonosító (TRID), válaszkód (RC), válaszüzenet (RT), engedélyszám (ANUM), kifizetett összeg (AMO), • Sikertelen megjelenítendő fizetés adatai: tranzakció azonosító (TRID), válaszkód (RC), válaszüzenet (RT)
Time-out elfogadóhely általi lekezelése Részletek: • Fizetőoldalról 10 perc elteltét követően lezárt státusz automatikus beállítása, majd e-mailben történő visszaigazolása – sikertelen fizetésnek minősül, paramétereket lásd előbb • Amennyiben nincs lehetőség a webáruházban tájékoztatni a vásárlót, akkor is email-ben kell felhívni a figyelmét a sikertelen fizetésre.
Visszaigazolás e-mailben kötelező tranzakciós adatokkal
[email protected]
52. oldal
Részletek: • Rendelés adatai mellett a képernyőn is kötelezően megjelenítendő banki tranzakciós adatok
EUR ár megjelenítéséhez árfolyam Részletek: • Forint összeg kötelező megjelenítése • Banki árfolyam tájékoztató jelleggel történő opcionális használata – fel kell hívni a vásárló figyelmét, hogy az árfolyam a mindenkori CIB Banki árfolyamon alapul tájékoztató jelleggel. A kártyabirtokos bankja valószínűleg más árfolyamot használ és a kártyabirtokos bankjában történik a konverzió. Eltérő devizanem esetén fontos – USA$, Angol Font, stb kártyával történő fizetéskor a kártyabirtokos bankja váltja át az eurós / forintos árfolyamot a kártya számlájának megfelelő devizanemre és azzal terheli meg a számlát! • Valuta eladási árfolyam alkalmazása (banki fizetőoldalon ez kerül megjelenítésre)
Elfogadóhely neve a banki fizetőoldalon Részletek: • Cégnév vagy a honlap URL-je
Vásárló azonosítása Részletek: • A tranzakció inicializásánál, az MSGT=10 stringben szereplő UID-nek egyértelműen be kell azonosítania az áruházba beregisztált vásárlót. II. JAVASOLT / OPCIONÁLIS Sikertelen fizetés esetén újrafizetés lehetőségének biztosítása • A vásárlói kosár tartalmát a banki válaszhoz javasolt igazítani. Csak akkor törlődjön a tartalma, ha a vásárló sikeres fizetést hajtott végre. Ekkor a banki válaszban az RC=00 tartalmat mutat, ami a sikeres fizetést jelzi a webáruház felé. • Az újrafizetés lehetősége a vásárlü szempontjából előnyös, téves kártyaadat, vagy visszalépés esetén nem kell újra összeválogatni a megvásárolni kívánt termékeket • A webáruház így biztosítja, hogy a vásárló kifizethesse a kosara tartalmát
Idegen nyelvű fizetőoldal alkalmazása
Részletek: • Nyelvkódok alkalmazása
[email protected]
53. oldal
2. SZ. MELLÉKLET Kártya jellegű hiba csoportjába tartozó kódok és kérdések: 03, 09, 12, 13, 20, 21, 22, 30, 34, 36, 42, 52, 54, 55, 56, 87, 88, 90 Kérjük ellenőrizze, hogy jól írta-e be a kártyaszámát! Kérjük ellenőrizze, hogy jól írta-e be a kártya lejárati dátumát! Kérjük ellenőrizze, hogy nem járt-e le a kártyája! Kérjük ellenőrizze, hogy EC/MC kártya esetén beírta-e a kártya hátoldalán az aláíráscsíkon szereplő szám utolsó három számjegyét (CVC kódot) ! Kérjük ellenőrizze, hogy internetes vásárlásra alkalmas-e a kártyája! Kérjük ellenőrizze, hogy Visa kártyájának hátoldalán szerepel-e a 3 számjegyű CVV kód! Ha igen, kérjük, írja be! Számla jellegű hiba csoportjába tartozó kódok és kérdések: 14, 15, 16, 17, 23, 24, 29, 32, 35, 45, 69, 70, 72, 74, 75, 76, 77, 78 Kérjük ellenőrizze, hogy van-e elegendő pénz a számláján a vásárlás lebonyolítására! Kérjük ellenőrizze, hogy nem lépte-e túl az engedélyezett limitjét! Kapcsolati jellegű hiba csoportjába tartozó kódok és kérdések: 08, 10, 19, 27, 31, 50, 60, 64, 65, 71, 86, 93, A2, A9 A tranzakció során valószínűleg megszakadt a vonal. Kérjük, próbálja meg újra. A tranzakció időtúllépés miatt sikertelen volt. Kérjük, próbálja meg újra. Technikai jellegű hiba csoportjába tartozó kódok és kérdések: 01, 02, 04, 05, 06, 07, 11, 18, 25, 26, 28, 33, 38, 39, 40, 41, 43, 44, 46, 49, 51, 53, 57, 61, 62, 63, 66, 67, 79, 8, 81, 85, 92, 94, 96, 98, R0, C2 Leggyakoribb hibák: 09 ismeretlen kártya: Nem internetes fizetésre alkalmas kártya, vagy nem létezik ilyen típusú kártya 22 A tranzakciót a kártyakibocsátó bank elutasította: Ebben az esetben csak a kibocsátó bank tudja megmondani mi a hiba. Ha kibocsátó bank azt mondja hogy rendben van részéről a kártya, internetes fizetésre alkalmas, van rajta fedezet, stb., akkor ki kell vizsgálni Verified by Visa szempontból A2 átmeneti hiba: Általában bankon belüli hiba szokott lenne, az EKI szerver ilyenkor visszautasítja a fizetési kísérleteket. Azonnal értesíteni kell az EKI rendszergazdákat, mert többnyire ilyenkor betelik egy puffer. C2 A vásárló nem engedélyezte a tranzakciót: A fizetőoldalon a vásárló rányomott a VISSZA gomba (nem a böngészőben hanem magán a fizetőoldalon elhelyezett gombra) TO/50 Time-out: 10-es üzenet indításától 10 perc telt el, ilyenkor a bank zárja a tranzakciót
[email protected]
54. oldal
További hibalehetőségek: 24 Nincs fedezet 50 Időtúllépés 86 Ismeretlen kártyatipus A1 Authorizációs hiba A9 Authorizációs hiba C1 Feldolgozhatatlan kártyaszám C2 A vásárló nem engedélyezte a tranzakciót C3 A vásárló nem engedélyezte a tranzakciót C4 Csalás C5 Kártyaszám hiba DE A tranzakció nem lett végrehajtva. R0 Eltérő összegek R1 Eltérése az előző lekérdezéshez képest R4 Nem CIB kártya R5 Nincs ilyen felhasználó azonosító Ehhez az a felhasználó azonosítóhoz nincs aktív kártya R6 engedélyezve. TO Időtúllépés
[email protected]
55. oldal
3. SZ. MELLÉKLET A fizetési folyamat: Webáruház
Bank
MSGT=10 összeállítása és beküldése a bankba a webáruházból: http://eki(t).cib.hu:8090/market.saki?_
RC=01 esetén új TRID-et kell a webáruháznak generálni. Egyéb RC kódnál lásd 3.5 bekezdést.
RC<>00
MSGT=20 összeállítása, a vásárló átirányítása a webáruházból a banki fizetőoldalra:
MSGT=11 – a bank küldi a választ a webáruházba. Ha RC=00, akkor sikeres a TRID befoglalálsa
RC=00
https://eki(t).cib.hu/customer.saki?_
A vásárló a bank fizetőoldaláról a jobb alsó vissza gombbal visszalép, eláll a fizetéstől.
A vásárló a bank fizetőoldalán megadja a kártyaadatait, majd a fizetés gombra kattintva visszakerül a banki fizetőoldalról a webáruházba.
MSGT=21 üzenettel a bank visszairányítja a vásárlót a webáruházba. MSGT=32 üzenettel a webáruház lezárja a tranzakciót.
MSGT=31 üzenet paramétereit kiértékeli a webáruház és ennek megfelelően közli a vásárlóval a fizetési folyamat eredményét.
A bank összeállítja a választ, amit az MSGT=31-es üzenetben elküld a webáruház részére.
Az MSGT=31-es üzenet többféle választ tartalmazhat, melyeket le kell kezelni a webáruháznak, többek között: RC=00 – az authorizáció sikeres volt. Olyan eset is lehetséges, hogy az authorizáció sikeres, de a terhelés nem következik be. Ez timeout miatt fordulhat elő, mely során a vásárló nem tér vissza a [email protected]
56. oldal
webáruház oldalára, melynek következtében a tranzakció reverzálásra, azaz sztornózásra kerül. 10 perc elteltével – amit javasolt 11 percre állítani - az MSGT=32 üzenettel le kell zárni a tranzakciót. Ekkor a contentben szerepelni fog egy RC kód – lásd következő lépést. Az MSGT=32 üzenet válaszát követően 10 perc múlva javasolt az MSGT=37 üzenettel lekérdezni historikusan a tranzakció lépéseit. Ennek history lépései: 10, 11, 20, 21, 55, 56. RC=xx – a tranzakció lezárásának kérése (MSGT=32) sikertelen volt. Az RC kód és RT szöveg adja meg a hiba okát. Amennyiben az RC=<érték> nagyobb, mint 2 karakter, úgy a 33-as üzenettel (MSGT=33) lehet bővebb információt kinyerni. (HTTP 500-as hibát ad vissza a böngésző, a content-ből kiolvasható az RC paraméter értéke.) Fontos, hogy bár az MSGT=33 üzenet felépítésében teljesen megegyezik az MSGT=32-es üzenettel, azt nem váltja ki. Az MSGT=33 üzenet csak és kizárólag lekérdezést végez, a tranzakció lezárásában nem vesz részt!
A következő lépések a hibaüzenet lekezelésének egy eljárását mutatja be: MSGT=31 üzenet paramétereit kiértékeli a webáruház és ennek megfelelően kell közölni vásárlóval a fizetési folyamat eredményét.
10 percen belül végzett MSGT=32-re adott válasz esetén
RC=00
A fizetés sikeres. A paramétereket közölni kell a vásárlóval: TRID, RC, RT, ANUM, AMO.
RC<>00
MSGT=31 bank válaszban lévő paramétereket közölni kell a vásárlóval:
Time out esetén
RC > 2 karakter (a böngészőben a contentből kiolvasható)
MSGT=33 üzenettel érdemes információt kérni.
TRID, RC, RT MSGT=31 válaszban lévő paramétereket közölni kell a vásárlóval: TRID, RC, RT, ANUM, AMO – ez utóbbi kettő üres!
[email protected]
57. oldal
