Document 311445
MERCHANT INTEGRATION MANUAL Integračný manuál obchodníka Názov Integračný manuál obchodníka Zabezpečenie Verejný dokument, prístupné Revízia 2.1 Integračný manuál obchodníka Tento dokument obsahuje diskrétne a dôverné informácie. Je výhradným majetkom spol. 24-‐pay vzhľadom na autorský zákon (Zákonč.618/2003 Z. z.). Dokument môže obsahovať osobné údaje a je nutné ho náležite spracovávať (Zákon č.428/2002 Z. z.). Neoprávnené kopírovanie, rozosielanie, rozširovanie a zdieľanie v akejkoľvek podobe je výhradne zakázané bez písomného povolenia schvaľovateľa dokumentu, alebo konateľa spoločnosti. Prosím, zvážte vplyv na životné prostredie pred tlačou tohto dokumentu a papierové kópie vytvárajte len v nutných prípadoch. Dokument je optimalizovaný pre obojstrannú tlač. 2 / 19 OBSAH 1 ÚVOD ............................................................................................................................................................................................ 4 1.1 Termíny a ustálené výrazy ............................................................................................................................................... 4 1.2 Stručná charakteristika systému 24pay ..................................................................................................................... 4 1.3 Obsah dokumentu ................................................................................................................................................................ 4 2 INTEGRÁCIA S 24PAY ............................................................................................................................................................ 4 2.1 Konfiguračná údaje ............................................................................................................................................................. 4 2.2 Process Flow ........................................................................................................................................................................... 5 2.2.1 Sekvenčný/Synchrónny response model ................................................................................................................. 5 2.2.2 Paralelný/Asynchrónny response model ................................................................................................................ 6 3 PROTOKOL PLATIEB ............................................................................................................................................................. 7 3.1 Požiadavka na realizáciu platby od obchodníka ..................................................................................................... 7 3.2 Kontrolný súčet .................................................................................................................................................................. 10 3.2.1 Bezpečnostný kľúč ......................................................................................................................................................... 10 3.2.2 Kontrolný súčet ............................................................................................................................................................... 10 3.2.3 SIGN ...................................................................................................................................................................................... 10 3.2.4 SIGN verifikácia ............................................................................................................................................................... 10 3.2.5 Realizácia platby ............................................................................................................................................................ 10 3.3 Notifikácia o statuse spracovania platby od 24pay systému ......................................................................... 11 3.4 Presmerovanie zákazníka do systému obchodníka ........................................................................................... 12 4 PRÍLOHY .................................................................................................................................................................................... 14 4.1 Predloha zasielanej XML štruktúry ........................................................................................................................... 14 4.2 Predloha tvorby podpisu ............................................................................................................................................... 15 4.2.1 Prípad požiadavky na realizáciu platby .............................................................................................................. 15 4.2.2 Prípad notifikácie o statuse spracovania platby .............................................................................................. 16 4.2.3 Code Samples .................................................................................................................................................................... 17 3 / 19 Integračný manuál obchodníka 1 ÚVOD 1.1 Termíny a ustálené výrazy PSP – payment service provider -‐ poskytovateľ platobnej služby. 24pay – automatizovaný systém platobnej inštitúcie -‐ poskytovateľ platobnej služby. Obchodník/Obchod/Merchant – online obchod/organizácia/entita poskytujúca tovar/služby, prijímajúca platby. Klient/zákazník/client – osoba nakupujúca tovar/služby, vykonávajúca platby. RURL – Redirection Return URL – URL adresa komunikačného rozhrania obchodu, kam je zákazník presmerovaný po úspešnom zahájení transakcie. NURL – Notification Return URL – URL adresa komunikačného rozhrania obchodu, kam sú zasielané notifikácie o zmene statusu platby prostredníctvom protokolu HTTP/HTTPS metódou POST v rámci tela requestu. 1.2 Stručná charakteristika systému 24pay 24pay Merchant API predstavuje moderné platobné riešenie, poskytujúce bezpečné, rýchle a flexibilné platobné operácie v prostredí Internetu. Okrem základnej funkcionality zabezpečujúcej prevod peňazí medzi zákazníkom a obchodníkom ponúka pestrú škálu služieb pre obe zúčastnené strany: rýchlosť, bezpečnosť, flexibilitu, podporu rôznych mien a krajín a nonstop servis. Pre koncových zákazníkov flexibilitu na úrovni veľkého množstva podporovaných koncových služieb pre vklady a výbery, jednoduchosť užívateľského rozhrania a bezpečnosť. Pre obchodníkov jednoduchú implementáciu, automatický prístup k množstvu platobných metód, inteligentný systém s vysokú úrovňou bezpečnosti a nadštandardným balíčkom AML (anti money laundering) a KYC (know your customer) procedúr. 1.3 Obsah dokumentu Účelom tohto dokumentu je popísať komunikačný protokol medzi webovým serverom obchodníka a platobným rozhraním systému 24pay. Slúži ako technická príručka pre služby poskytované systémom 24pay a obsahuje popis krokov ako sa korektne pripojiť a komunikovať s jeho platobným rozhraním. Dokument nie je návodom na vytváranie web stránok. Jeho úlohou je vymenovať a popísať podmienky, ktoré musí web sídlo obchodníka spĺňať za účelom úspešnej realizácie platobnej služby. 2 INTEGRÁCIA S 24PAY 2.1 Konfiguračná údaje Nasledujúca sekcia popisuje množinu údajov, ktoré si navzájom medzi sebou vymenia systém obchodníka a systém 24pay. 4 / 19 Obchodník uvádza nasledujúce údaje: -
RURL (sekcia 2.2.1 below, sekcia 2.2.2 below) -
NURL (sekcia 2.2.1 below, sekcia 2.2.2 below) 24pay poskytuje obchodu nasledovné údaje: -
Mid (3.1 below) -
EshopId (3.1 below) -
Key (3.2.1 below) -
collection<paymentRequestGateURL> (1 below) 2.2 Process Flow Účelom tejto sekcie je načrtnúť processing model spracovania a realizácie platobnej relácie zobrazením interakcie medzi aktérmi: klient – obchodník – 24pay. Platobná stránka obchodníka obsahuje odkaz na poskytovateľa online platobného styku predstavovaného systémom 24pay. Zákazník, ktorý si vybral 24pay ako želanú platobnú metódu, zašle zo systému obchodníka do systému 24pay žiadosť o realizáciu platby. Žiadosť obsahuje predpísanú množinu údajov potrebných pre spracovanie a realizáciu platobnej relácie. V prípade nevyhovujúceho formátu/obsahu parametrov prijatej žiadosti je zákazník presmerovaný na stránku systému 24-‐pay informujúcu o neúspešnej požiadavke o realizáciu platobnej relácie. V opačnom prípade je klient presmerovaný na platobný portál bankovej inštitúcie, kde vyplní údaje vzťažmo k svojej platobnej karte (číslo, exspirácia, CV kód). Zákazník nemá možnosť editovať preddefinované položky platobnej relácie: -
účet príjemcu/obchodníka, -
suma, -
mena, -
variabilný symbol, -
konštantný symbol. Klient následne potvrdí, alebo zruší platbu. 24pay systém realizuje potrebné kroky spracovania platobnej relácie. 2.2.1
Sekvenčný/Synchrónny response model 24pay systém zasiela notifikáciu o výsledku realizácie platobnej relácie obchodníkovi na adresu špecifikovanú konfiguračnou položkou NURL. Server side obchodníka má povinnosť reagovať odpoveďou HTTP status 200 OK, potvrdzujúcou prijatie odpovede. V systéme obchodníka je možné spúšťať dodatočné kroky týkajúce sa danej transakcie. Prijatie akejkoľvek inej odpovede zo strany obchodníka bude považované za neúspešné doručenie notifikácie. Po prijatí OK odpovede pre notifikáciu je zákazník okamžite presmerovaný metódou GET na stránku obchodníka špecifikovanú konfiguračnou položkou RURL. Návratové adresy obsahujú reťazec parametrov informujúcich o výsledku spracovania platobnej relácie, na základe ktorých systém obchodníka oboznámi zákazníka o úspešnom, či neúspešnom spracovaní. Návratové adresy slúžia iba pre informatívne účely, na ich základe nie je možné vykonávať žiadne rozhodnutia. 5 / 19 Integračný manuál obchodníka Obrázok 1. ProcessFlow -‐ synchronous response model 2.2.2
Paralelný/Asynchrónny response model 24pay systém presmeruje zákazníka metódou GET na stránku obchodníka špecifikovanú konfiguračnou položkou RURL. Návratové adresy obsahujú reťazec parametrov informujúcich o výsledku spracovania platobnej relácie, na základe ktorých systém obchodníka oboznámi zákazníka o úspešnom, či neúspešnom spracovaní. Návratové adresy slúžia iba pre informatívne účely, na ich základe nie je možné vykonávať žiadne rozhodnutia. 24pay systém zasiela notifikáciu o výsledku realizácie platobnej relácie obchodníkovi na adresu špecifikovanú konfiguračnou položkou NURL. Server side obchodníka má povinnosť reagovať odpoveďou HTTP status 200 OK, potvrdzujúcou prijatie odpovede. V systéme obchodníka je možné spúšťať dodatočné kroky týkajúce sa danej transakcie. V tomto prípade je notifikácia zaslaná na stranu obchodníka asynchrónne, t.j. je odosielaná pred/zároveň/po presmerovávacích HTTP request-‐och. Aplikácia obchodu by sa mala snažiť v prvom rade potvrdiť prijatie notifikačnej správy spätným odoslaním reťazca OK, a následne spúšťať interné spracovanie prijatej informácie. Prijatie akejkoľvek inej, či oneskorenej odpovede zo strany obchodníka bude považované za neúspešné doručenie notifikácie. V prípade, že systém 24pay v predpísanom časovom rozmedzí neprijme potvrdenie o prijatí notifikačnej správy, bude jej odosielanie opakovať v definovaných časových intervaloch. Pri asynchrónnom modeli sa jedná o zasielanie odpovede s resultom PENDING. 6 / 19 Obrázok 2. ProcessFlow -‐ asynchronous response model 3 Protokol platieb 3.1 Požiadavka na realizáciu platby od obchodníka Pre zaslanie novej platobnej žiadosti je nutné na stránku webového sídla obchodu umiestniť príslušný formulár, ktorý presmeruje zákazníka na 24pay platobnú bránu paymentRequestGateURL. URL 24pay platobná brána ( viď 2.1 ): paymentRequestGateURL = https://admin.24-‐pay.eu/pay_gate/paygt**1 Podmienkou je vytvorenie HTTPS požiadavky metódou POST. Údaje budú kódované vo forme application/x-‐www-‐form-‐urlencoded – t.j. ide o obdobu odoslania bežného HTML formulára. Zoznam parametrov vidíte v nasledujúcej tabuľke: Tabuľka 1. Payment request -‐ zoznam parametrov 1
Suffix identifikátora platobnej brány. Hodnota tohto parametra je vecou špecifikácie konkretizovanej pri podpise zmluvy medzi
systémom 24pay a obchodníkom.
7 / 19 Integračný manuál obchodníka Parameter Formát Dĺžka Povinný 2
údaj Popis/Príklad M R O Mid Alpha-‐numeric 8 ● Merchant identifier – identifikátor obchodníka. Napr.: 1a2B3c4D (case sensitive!). EshopId 0 [ numeric ] 1..10 ● E-‐shop identifier – identifikátor e-‐shop entity vzťažmo k entite obchodníka. PreAuthProvided true/false 4/5 ● Voľba predautorizovaného platobného príkazu. Povolené hodnoty: true/false ( case sensitive!). Merchant system transaction identifier – jednoznačný/jedinečný identifikátor platby poskytnutý obchodníkom ( v drvivej väčšine prípadov predstavovaný variabilným symbolom ). MsTxnId Alpha-‐numeric 1..32 ● ● Suma, ktorú klient prevádza na obchodníkov účet. Oddeľovačom desatinnej časti je bodka. Desatinná časť zastúpená dvoma číslicami. Amount #0.00 1..6,2 CurrNumCode 000 [ numeric ] 3 ● ISO 4217 currency numeric code. (http://iso4217.com/) CurrAlphaCode AAA [ alhabetic ] 3 ● ISO 4217 currency alphabetic code. (http://iso4217.com/) RURL NURL URL URL 256 256 ● Redirection Return URL – URL adresa komunikačného rozhrania obchodu, kam je zákazník presmerovaný po úspešnom zahájení transakcie. V prípade prítomnosti prekryje konfigurovanú položku RURL. ● Notification Return URL – URL adresa komunikačného rozhrania obchodu, kam sú zasielané notifikácie o zmene statusu platby prostredníctvom protokolu HTTP/HTTPS metódou POST v rámci tela requestu. V prípade prítomnosti prekryje konfigurovanú položku NURL. ISO 639-‐1 alpha-‐2 language code. (http://ftp.ics.uci.edu/pub/ietf/http/related/iso6
39.txt http://en.wikipedia.org/wiki/List_of_ISO_639-‐
1_codes) sk, cz, en, de, hu, es, fr, it, pl. Štandardne sk. ● ● 3..10 ● Identifikátor zákazníka v systéme obchodníka (case sensitive!). Alphabetic 2..50 ● Zákazník – krstné meno. FamilyName Alphabetic 2..50 ● Zákazník – priezvisko. Email Alha-‐numeric 6..128 ● Zákazník – adresa emailového účtu v systéme obchodníka. Phone Alha-‐numeric 8..25 ● Zákazník – telefónny kontakt v systéme obchodníka. Street Alpha-‐numeric 5..50 ● ● Zákazník – ulica momentálneho bydliska. Zip Alpha-‐numeric 1..10 ● ● Zákazník – poštové smerovacie číslo momentálneho bydliska. City Alphabetic 2..30 ● ● Zákazník – mesto/lokácia momentálneho LangCode AA 2 ClientId Alpha-‐numeric FirstName 2
M - mandatory/povinný
8 / 19 R - recommended/odporúčaný
O - optional/voliteľný
bydliska. Country AAA (alphabetic) 3 ● Zákazník – krajina momentálneho bydliska. ISO 3166-‐1 alpha-‐3 country code. (http://en.wikipedia.org/wiki/ISO_3166-‐1_alpha-‐
3) Timestamp yyyy-‐MM-‐dd HH:mm:ss 19 ● Časová pečiatka tvorby platobnej požiadavky. Oddeľovačom dátumovej a časovej položky je znak medzera! Sign Alpha-‐numeric 32 ● Kontrolny súčet zasielaných parametrov. (case insensitive!) Pozor! Je potrebné si uvedomiť, resp. brať v úvahu ohľad na situáciu, keď zákazník v prostredí systému obchodníka zvolí nesprávnu platobnú metódu/bránu (zbrklo klikol; stlačil enter; zvolil platbu kartou, ktorú v zapätí nevie pri sebe nájsť nakoľko ju zabudol; zvolil banku X, pritom účet má v banke Y, atď.). Svoj omyl si zákazník vo väčšine prípadov uvedomí až v momente, keď je presmerovaný na stránku daného poskytovateľa platobnej metódy/brány (credit card processing, instant-‐payment/ internet-‐banking processing, bank-‐transfer processing, other processing). V drvivej väčšine prípadov (takmer skoro vždy), sa zákazník pokúša vracať krok za krokom späť v prostredí svojho internetového prehliadača, s cieľom zmeniť na stránke obchodníka voľbu ním preferovanej platobnej metódy/brány. V týchto prípadoch je nutné zaistiť, aby nasledovne inicializovaná platobná požiadka z prostredia systému obchodníka v svojom tele niesla novú hodnotu parametra MsTxnId (a to aj navzdory faktu, že z pohľadu obchodu ide stále o tú istú objednávku). Vytvorenie novej hodnoty parametra MsTxnId je nevyhnutné, nakoľko neoddeliteľnou súčasťou pre+post-‐
processingu, vrátane presmerovania zákazníka do prostredia sprostredkovateľa platobného styku sú v systéme 24pay ukladané a monitorované stavy daného transakčného záznamu. Následkom opakovaného použitia rovnakej hodnoty parametra MsTxnId v rámci platobnej požiadavky sú viaceré negatívne následky, napr.: -
systém obchodníka v rámci n-‐násobne prijatej NURL správy nemá ako určiť, ktorej transakčnej položky v jeho systéme sa odpoveď týka. -
systém 24pay generuje vzťažmo pre každú platobnú požiadavku ( teda aj pre hodnotu MsTxnId obsiahnutú v jej tele ) unikátny/jednoznačný identifikátor PspTxnId, čím rieši problém opakovane zasielanej hodnoty parametra MsTxnId v rámci platobnej požiadavky. Pracovník na strane systému obchodníka tým pádom nepáruje platby svojho systému voči systému 24pay inštinktívne použitím hodnôt interného parametra MsTxnId, avšak logicky použitím externého parametra PspTxnId, ktorý tento problém rieši. Pred odoslaním platobnej požiadavky je nutné zaistiť, aby hodnota parametra MsTxnId bola jedinečná taktiež aj v tých prípadoch, keď zákazník v prostredí systému obchodníka zmenil voľbu platobnej metódy/brány pre realizáciu jednej a tej istej objednávky. Jednoduchým mechanizmom zaisťujúcim jedinečnosť hodnoty parametra MsTxnId, môže byť logika založená na princípe prepojenia interného čísla objednávky/identifikátora klienta/... zo systému obchodníka s časovým razítkom zastúpeným v tele platobnej požiadavky hodnotou parametra Timestamp. ( napr. MsTxnId = OrderId/MsClientId + Timestamp). 9 / 19 Integračný manuál obchodníka 3.2 Kontrolný súčet Pre každú požiadavku na realizáciu platby zo strany obchodu a notifikáciu o statuse spracovania platby zo strany 24pay systému, je vytvorený kontrolný súčet. Prostredníctvom kontrolného súčtu možno overiť integritu a autenticitu údajov. 3.2.1
Bezpečnostný kľúč Pre každého obchodníka je vygenerovaný bezpečnostný kľúč key dĺžky 32B (32 B = 256 bits). Obchodník získa kľúč key (viď 2.1) v podobe reťazca reprezentujúceho jeho hexadecimálny zápis, resp. reťazca 64 (slovom šesťdesiatich štyroch) znakov. Okrem bezpečnostného kľúča, bude pre výpočet kontrolného súčtu obchodník potrebovať aj inicializačný vektor IV dĺžky 16B = 128 bits. Inicializačný vektor je vytvorený zreťazením parametra Mid3 zo svojou reverznou podobou. Týmto spôsobom získaná sekvencia 16 (slovom šestnástich) znakov reprezentuje inicializačný vektor IV dĺžky 16 B. 3.2.2
Kontrolný súčet Pred komunikáciou je vytvorený kontrolný súčet, resp. bezpečnostný podpis nasledovným spôsobom: a) Zreťazením podpisom chránených parametrov v predpísanom poradí sa vytvorí REŤAZEC/MESSAGE, ktorého obsah bude predmetom šifrovania. b) Vytvorený reťazec je transformovaný na HASH/MD (message digest) pevnej dĺžky (20 B = 160 bits) pomocou hashovacej funkcie SHA1. c) Takto získaný "odtlačok" MD je následne šifrovaný symetrickým algoritmom AES4 použitím: a. inicializačného vektora IV b. a definovaného bezpečnostného kľúča key d) Výstupom je bezpečnostný podpis dĺžky 32 B = 256 bits. Prvých 16 B (slovom šestnásť bajtov) podpisu je konvertovaných na reťazec zodpovedajúci hexadecimálnemu zápisu tejto časti podpisu. Pôvodný otvorený text MD je týmto spôsobom transformovaný na šifrovaný text reprezentujúci bezpečnostný podpis o dĺžke 32 (slovom tridsaťdva) znakov. 3.2.3
SIGN Strana odosielateľa požiadavky zasiela bezpečnostný podpis v rámci komunikácie ako hodnotu parametra SIGN. 3.2.4
SIGN verifikácia Strana príjemcu požiadavky z parametrov tejto požiadavky vytvorí rovnakým spôsobom kontrolný bezpečnostný podpis a porovná ho s hodnotou prijatého parametra SIGN. 3.2.5
Realizácia platby Platobná inštitúcia 24pay zrealizuje požiadavku na realizáciu platby zo strany obchodu len v prípade rovnosti bezpečnostných kľúčov. Pre požiadavku na realizáciu platby zo strany obchodu sú predmetom zreťazenia v predpísanom poradí nasledovné parametre (operátor ⊕ predstavuje operáciu reťazenia znakov): 3
4
Dĺžky 8 znakov, množina alfanumerických znakov {a-zA-Z0-9}, 1 char == 1 byte.
Blokový symetrický kryptografický algoritmus; key-size 256bits; block-size 128 bits; mód AES/CBC/PKCS7Padding. 10 / 19 REŤAZEC/MESSAGE = Mid ⊕ Amount ⊕ CurrencyAlphaCode ⊕ MsTxnId ⊕ FirstName ⊕ FamilyName ⊕ Timestamp Pre notifikáciu o statuse spracovania platby zo strany 24pay systému sú predmetom zreťazenia v predpísanom poradí nasledovné parametre: REŤAZEC/MESSAGE = Mid ⊕ Amount ⊕ CurrencyAlphaCode ⊕ PspTxnId ⊕ MsTxnId ⊕ Timestamp ⊕ Result 3.3 Notifikácia o statuse spracovania platby od 24pay systému Po ukončení spracovania žiadosti na realizáciu platby zo strany obchodu 24pay systém notifikuje o statuse spracovania platby. Správa je odoslaná v rámci HTTP POST požiadavky adresovanej na NURL. Údaje týkajúce sa danej platby sú prenášané vo forme štruktúry majúcej XML formát ako hodnota parametra params. Predlohu výzoru si môžete pozrieť medzi prílohami, viď sekciu 4.1.. Tabuľka 2. Zoznam uzlov XML štruktúry Node/node attribute Formát Popis/Príklad M R O Response Group Sign Povinný údaj Dĺžka Root node Alpha-‐numeric 32 Identification Group ● Kontrolny súčet zasielaných parametrov. Parent node: <Transaction> MsTxnId Alpha-‐numeric 1..32 ● Merchant system transaction identifier – jednoznačný/jedinečný identifikátor platby poskytnutý obchodníkom ( v drvivej väčšine prípadov predstavovaný variabilným symbolom ). PspTxnId Numeric 1..32 ● Payment service provider transaction identifier – jednoznačný/jedinečný identifikátor platby generovaný interne systémom 24pay. Presentation Group Parent node: <Transaction> Amount #0.00 1..10,2 ● Suma, ktorú klient prevádza na obchodníkov účet. Oddeľovačom desatinnej časti je bodka. Desatinná časť zastúpená dvoma číslicami. Currency AAA [ alhabetic ] 3 ● ISO 4217 currency alphabetic code. (http://iso4217.com/) Contact Group Parent node: <Customer> Email Alha-‐numeric 6..128 Phone Alha-‐numeric 8..25 Address Group ● ● Zákazník – adresa emailového účtu v systéme obchodníka. Zákazník – telefónny kontakt v systéme obchodníka. Parent node: <Customer> Street Alpha-‐numeric 5..50 ● Zákazník – ulica momentálneho bydliska. Zip Alpha-‐numeric 1..10 ● Zákazník – poštové smerovaci číslo momentálneho bydliska. City Alphabetic 2..30 ● Zákazník – mesto/lokácia momentálneho 11 / 19 Integračný manuál obchodníka bydliska. Country Alphabetic 3 Name Group ● Zákazník – krajina momentálneho bydliska. ISO 3166-‐1 alpha-‐3 country code. (http://en.wikipedia.org/wiki/ISO_3166-‐1_alpha-‐
3) Parent node: <Customer> Given Alphabetic 2..15 ● Zákazník – krstné meno. Family Alphabetic 2..15 ● Zákazník – priezvisko. Processing Group Parent node: <Transaction> Timestamp yyyy-‐MM-‐dd HH:mm:ss 19 ● Časová pečiatka tvorby bezpečnostného podpisu. Časová pečiatka tvorby platobnej požiadaky. Oddeľovačom dátumovej a časovej položky je znak medzera! Result OK/FAIL/PENDIN
5
G 2/4 ● Transakcia bola korektne spracovaná/Transakcia nebola korektne spracovaná a teda platba za objednaný tovar, resp. služby sa nezrealizovala. Reason Alpha-‐numeric 2..1024 ●
Transakcia bola korektne spracovaná/Transakcia nebola korektne spracovaná a teda platba za objednaný tovar, resp. služby sa nezrealizovala. Príklad notifikácie: NURL?params=<?xml version"1.0" encoding="UTF-‐8"?><Response>* * *</Response> 3.4
Presmerovanie zákazníka do systému obchodníka Po dokončení platby je klient presmerovaný späť do systému obchodníka na RURL, ktoré uvádza obchod. Presmerovanie je vykonané HTTP GET požiadavkou, pričom reťazec dopytu obsahuje parametre nesúce informáciu o úspešnom, či neúspešnom výsledku spracovania platby. Je nutné si uvedomiť, že RURL slúži iba pre informatívne účely. Na základe údajov prijatých v rámci presmerovania späť na systém obchodníka nie je možné vykonávať žiadne rozhodnutia. Zoznam parametrov zaslaných v reťazci dopytu je nasledovný: Tabuľka 3. Zoznam parametrov v reťazci dopytu Parameter Formát Dĺžka Popis/Príklad MsTxnId Numeric 1..256 Merchant system transaction identifier – jednoznačný identifikátor platby poskytnutý obchodníkom ( v drvivej väčšine prípadov predstavovaný variabilným symbolom ). Amount #0.00 1..10,2 Suma, ktorú klient prevádza na obchodníkov účet. Oddeľovačom desatinnej časti je bodka. Desatinná časť zastúpená dvoma číslicami. CurrCode AAA [ alhabetic ] 3 ISO 4217 currency alphabetic code. ( http://iso4217.com/ ) Result OK/FAIL 2/4 Transakcia bola korektne spracovaná/Transakcia nebola korektne spracovaná a teda platba za objednaný tovar, resp. služby sa nezrealizovala. 5
UPOZORNENIE: Zákazníkom neodporúčame v čase od 21:30 - 01:00 h uskutočňovať platbu prostredníctvom platobného produktu
SporoPay, nakoľko v tomto čase je v Slovenskej sporiteľni vykonávaná uzávierka bankového systému. Z toho dôvodu nebude zo strany
Slovenskej sporiteľne doručená včas (do 30 minút) informácia internetovej aplikácii o výsledku spracovania transakčnej požiadavky.
12 / 19 Poznámka: -‐
nakoľko presmerovanie slúži len pre informatívne účely, nie je obsah parametrov HTPP GET dopytu na RURL zabezpečený kontrolným súčtom tak, ako tomu je pri notifikáčnej správe zaslanej na NURL (týmto spôsobom je ošetrená aj situácia, kedy sa zákazník nevráti na webové stránky systému obchodníka, ak zavrie -‐ unáhlene, zbrklo, rýchlo, … -‐ okno prehliadača skôr než dôjde k finálnemu presmerovaniu), -‐
reťazec dopytu (query string) obsahuje vždy všetky vymenované údaje. Príklady presmerovania: RURL?MsTxnId=***&Amount=**.**&CurrCode=***&Result=OK RURL?MsTxnId=***&Amount=**.**&CurrCode=***&Result=FAIL 13 / 19 Integračný manuál obchodníka 4 Prílohy 4.1 Predloha zasielanej XML štruktúry <?xml version="1.0" encoding="UTF-‐8"?> <Response sign="12345678901234567890123456789012"> <Transaction> <Identification> <MsTxnId>1234567890</MsTxnId> <PspTxnId>0987654321</PspTxnId> </Identification> <Presentation> <Amount>12.50</Amount> <Currency>EUR</Currency> </Presentation> <Customer> <Contact> <Email>[email protected]</Email> <Phone>111 222 333</Phone> </Contact> <Address> <Street>Demo ulica 2548/12</Street> <Zip>01526</Zip> <City>Bratislava</City> <Country>SVK</Country> </Address> <Name> <Given>Jan</Given> <Family>Pokusny</Family> </Name> </Customer> <Processing> <Timestamp>2012-‐03-‐15 12:56:07.548</Timestamp> <Result>OK</Result> <Reason code="00">Successful Processing</Reason> </Processing> </Transaction> </Response> 14 / 19 4.2 Predloha tvorby podpisu 4.2.1
Prípad požiadavky na realizáciu platby Key IV Mid Amount CurrencyAlphaCode MsTxnId FirstName FamilyName Timestamp Sign 1234567812345678123456781234567812345678123456781234567812345678 {0x58, 0x32, 0x34, 0x35, 0x6e, 0x53, 0x4f, 0x33, 0x33, 0x4f, 0x53, 0x6e, 0x35, 0x34, 0x32, 0x58} X245nSO3 10.20 EUR 1032071502 Ján Kenáčnibuk 2014-‐03-‐24 12:03:56 2835616656ED65708D81642E9C12A20B Detailný popis algorimizácie jednotlivých krokov výpočtu kontrolného súčtu bližšie popísaného sekciou 3.2 4.2.1
• hexKey = 1234567812345678123456781234567812345678123456781234567812345678
• length 64 characters
4.2.1
• byte[] keyBytes = {0x12, 0x34, 0x56, 0x78, 0x12, 0x34, 0x56, 0x78, . . . . . . , 0x34, 0x56, 0x78}
• length 32B = 256 bits
4.2.1
• txtIV = X245nSO33OSn542X
• length 16 characters
4.2.1
• byte[] IV= {0X58, 0X32, 0X34, 0X35, 0X6E, 0X53, 0X4F, 0X33, 0X33, 0X4F, 0X53, 0X6E, 0X35, 0X34,
0X32, 0X58}
• length 16B = 128 bits
4.2.2 a
• message = X245NSO310.20EUR1032071502JánKenáčnibuk2014-03-24 12:03:56
• byte[] hash/md = SHA-1(message) = {0XE6, 0XBC, 0X1D, 0XE2, 0XCF, 0X85, 0X7C, 0X24, 0X26,
0X33, 0XE4, 0X7F, 0X5D, 0X5B, 0XCB, 0X03, 0XDD, 0X24, 0XC8, 0X13}
4.2.2 b • length 20B = 160bits
• byte[] signBytes = {0X28, 0X35, 0X61, 0X66, 0X56, 0XED, 0X65, 0X70, 0X8D, 0X81, 0X64, 0X2E,
0X9C, 0X12, 0XA2, 0X0B, 0X39, 0XD2, 0X76, 0X9B, 0X0A, 0XDF, 0X0A, 0X4A, 0X5A, 0X5B, 0X73,
4.2.2 c 0XB4, 0X8B, 0XC3, 0X7D, 0X55}
• length 32B = 256 bits
4.2.2 d
• sign = 2835616656ED65708D81642E9C12A20B
15 / 19 Integračný manuál obchodníka 4.2.2
Prípad notifikácie o statuse spracovania platby Key 1234567812345678123456781234567812345678123456781234567812345678 {0x58, 0x32, 0x34, 0x35, 0x6e, 0x53, 0x4f, 0x33, 0x33, 0x4f, 0x53, 0x6e, 0x35, 0x34, 0x32, 0x58} IV Mid X245nSO3 Amount 10.20 CurrencyAlphaCode EUR PspTxnId 0987654321 MsTxnId 1032071502 Timestamp 2014-‐03-‐24 12:03:56 Result OK Sign 7BACB43F916802E541E4E894E2A0D586 Detailný popis algorimizácie jednotlivých krokov výpočtu kontrolného súčtu bližšie popísaného sekciou 3.2 4.2.1
• hexKey = 1234567812345678123456781234567812345678123456781234567812345678
• length 64 characters
4.2.1
• byte[] keyBytes = {0x12, 0x34, 0x56, 0x78, 0x12, 0x34, 0x56, 0x78, . . . . . . , 0x34, 0x56, 0x78}
• length 32B = 256 bits
4.2.1
• txtIV = X245nSO33OSn542X
• length 16 characters
4.2.1
• byte[] IV= {0X58, 0X32, 0X34, 0X35, 0X6E, 0X53, 0X4F, 0X33, 0X33, 0X4F, 0X53, 0X6E, 0X35, 0X34,
0X32, 0X58}
• length 16B = 128 bits
4.2.2 a
• message = X245nSO310.20EUR098765432110320715022014-03-24 12:03:56OK
• byte[] hash/md = SHA-1(message) = {0XD7, 0X43, 0XB6, 0X56, 0XF2, 0XF2, 0XE4, 0X2B, 0X7A,
0X77, 0XE4, 0X38, 0X18, 0X3D, 0X12, 0X19, 0X95, 0X8F, 0X90, 0XD3 }
4.2.2 b • length 20B = 160bits
• byte[] signBytes = {0X7B, 0XAC, 0XB4, 0X3F, 0X91, 0X68, 0X02, 0XE5, 0X41, 0XE4, 0XE8, 0X94,
0XE2, 0XA0, 0XD5, 0X86, 0X7E, 0X76, 0XB0, 0XB7, 0X0E, 0X57, 0XC2, 0XF5, 0X98, 0X09, 0X81,
4.2.2 c 0X17, 0XF1, 0X4D, 0X75, 0XA3}
• length 32B = 256 bits
4.2.2 d
• sign = 7BACB43F916802E541E4E894E2A0D586
16 / 19 4.2.3 Code Samples a) .NET framework 2.0 (C#) public static string AesEncrypt( string message, int keySize, int blockSize,
PaddingMode paddingMode , CipherMode cipherMode,
string AES_HEX_Key, string AES_TXT_IV)
{
byte[] hash = GetSha1(message);
RijndaelManaged aes = new RijndaelManaged();
aes.KeySize = keySize;
aes.BlockSize = blockSize;
aes.Padding = paddingMode;
aes.Mode = cipherMode;
aes.Key = ConvertHexStringToByteArray(AES_HEX_Key);
aes.IV = Encoding.UTF8.GetBytes(AES_TXT_IV);
ICryptoTransform encryptor = aes.CreateEncryptor(aes.Key, aes.IV);
byte[] encrypted = null;
using (MemoryStream ms = new MemoryStream()) {
using (var cs = new CryptoStream(ms, encryptor, CryptoStreamMode.Write)) {
cs.Write(hash, 0, hash.Length);
}
encrypted = ms.ToArray();
}
return ConvertByteArrayToHexString(encrypted);
}
b) .NET framework 2.0 (VB) Public Shared Function AesEncrypt(message As String, keySize As Integer, blockSize As Integer, _
paddingMode As PaddingMode, cipherMode As CipherMode, _
AES_HEX_Key As String, AES_TXT_IV As String) As String
Dim hash As Byte() = GetSha1(message)
Dim aes As New RijndaelManaged()
aes.KeySize = keySize
aes.BlockSize = blockSize
aes.Padding = paddingMode
aes.Mode = cipherMode
aes.Key = ConvertHexStringToByteArray(AES_HEX_Key)
aes.IV = Encoding.UTF8.GetBytes(AES_TXT_IV)
Dim encryptor As ICryptoTransform = aes.CreateEncryptor(aes.Key, aes.IV)
Dim encrypted As Byte() = Nothing
Using ms As New MemoryStream()
Using cs = New CryptoStream(ms, encryptor, CryptoStreamMode.Write)
cs.Write(hash, 0, hash.Length)
End Using
encrypted = ms.ToArray()
End Using
Return ConvertByteArrayToHexString(encrypted)
End Function
17 / 19 Integračný manuál obchodníka c) .NET framework 3.5 (C#) public static string AesEncrypt( string message, byte[] Key, byte[] IV, PaddingMode paddingMode , CipherMode
cipherMode)
{
byte[] hash = GetSha1(message);
AesManaged aes= new AesManaged();
aes.Key = Key;
aes.IV = IV;
aes.Mode = cipherMode;
aes.Padding = paddingMode;
ICryptoTransform encryptor = aes.CreateEncryptor(aes.Key, aes.IV);
byte[] encrypted = null;
using (MemoryStream ms = new MemoryStream()) {
using (var cs = new CryptoStream(ms, encryptor, CryptoStreamMode.Write)) {
cs.Write(hash, 0, hash.Length);
}
encrypted = ms.ToArray();
}
return ConvertByteArrayToHexString(encrypted);
}
d) .NET framework 3.5 (VB) Public Shared Function AesEncrypt(message As String, Key As Byte(), IV As Byte(), paddingMode As PaddingMode,
cipherMode As CipherMode) As String
Dim hash As Byte() = GetSha1(message)
Dim aes As New AesManaged()
aes.Key = Key
aes.IV = IV
aes.Mode = cipherMode
aes.Padding = paddingMode
Dim encryptor As ICryptoTransform = aes.CreateEncryptor(aes.Key, aes.IV)
Dim encrypted As Byte() = Nothing
Using ms As New MemoryStream()
Using cs = New CryptoStream(ms, encryptor, CryptoStreamMode.Write)
cs.Write(hash, 0, hash.Length)
End Using
encrypted = ms.ToArray()
End Using
Return ConvertByteArrayToHexString(encrypted)
End Function
18 / 19 e) PHP function sign($data,$iv,$hexKey){
$_cipher = mcrypt_module_open(MCRYPT_RIJNDAEL_128, '', MCRYPT_MODE_CBC, '');
$block = mcrypt_get_block_size('des', MCRYPT_MODE_CBC);
$pad = $block - (strlen($data) % $block);
$data .= str_repeat(chr($pad), $pad);
mcrypt_generic_init($_cipher, $hexKey, $iv);
$result = mcrypt_generic($_cipher, $data);
mcrypt_generic_deinit($_cipher);
return strtoupper(substr(bin2hex($result),0,32));
}
19 / 19
© Copyright 2025