Transakční rozhraní interního platebního systému IPS
Interní platební systém (IPS) spravuje finanční účty klientů (zaměstnanců, studentů, hostů) a zajištuje platební transakce prováděné uvnitř organizace (vklady, výběry, úhrady poplatků, úhrady služeb (stravování, ubytování, vstupné, půjčovné, kopírování apod. nebo úhrady zboží). Níže je popisováno standardní datové rozhraní IPS pro provádění kreditních a debetních transakcí ze strany napojených externích systémů.
Základní koncepce řešení
Komunikace mezi platebním zařízením (platební terminál, pokladní terminál nebo aplikace poskytovatele služeb) a systémem IPS je založena na výměně zpráv metodou Požadavek/Odpověď. Zprávy mají tvar standardních XML zpráv transportovaných prostřednictvím protokolu HTTPS. Vlastní XML schémata jednotlivých zpráv jsou popsána níže. Každé platební zařízení se k IPS připojuje prostřednictvím HTTPS protokolu a za tímto účelem je vybaveno odpovídajícím klientským certifikátem prokazujícím identitu připojovaného místa. Pro potřeby šifrování se doporučuje použití klíčů s minimální velikostí 128 bitů.
Pokud aplikace poskytovatele služeb koncentruje několik fyzických terminálů poskytujících služby v rámci IPS, musí tato aplikace zajistit identifikaci každého fyzického platebního terminálu pro potřeby IPS. Zabezpečení proti zneužití na úrovni platebních zařízení je na zodpovědnosti dodavatele nebo provozovatele těchto zařízení. Schválení připojení jednotlivých platebních zařízení je v kompetenci provozovatele IPS a na něm je též odborné posouzení bezpečnosti připojovaného zařízení s ohledem na bezpečnost provozu IPS.
Pro identifikaci účtů v rámci IPS lze použít osobní číslo, číslo účtu IPS nebo identifikační kartu.
Osobní číslo nebo číslo účtu IPS lze použít pouze v případě, že platební zařízení provedlo ověření identity osoby proti autorizačnímu serveru, který vrátil příslušnou identifikaci nebo se jedná o platební zařízení s pověřenou obsluhou, která provedla ověření identity jiným způsobem nebo se jedná o autonomní platební zařízení, které čerpá identity z autoritativního zdroje. V jiných případech nesmí být identifikace osobním číslem nebo číslem účtu IPS použita.
Typické schéma připojení platebních zařízení
V následujícím schématu jsou barevně znázorněna vybraná platební zařízení podle charakteru komunikace platebního zařízení s IPS.
Obr. 1
- Žlutá – Internetová aplikace poskytovatele služeb, která pro ověření a provedení transakce využívá internetové platební brány. Platební brána využívá pro ověření uživatele LDAP a pro identifikaci účtu osobní číslo uživatele. Každá internetová aplikace se musí internetové platební bráně identifikovat obdobně jako platební terminál.
- Zelená – Řešení, kdy je větší množství fyzických zařízení (terminálů SafeQ) připojeno prostřednictvím serveru, k identifikaci se používají identifikační karty a server musí odlišovat jednotlivá fyzická zařízení.
- Oranžová – Samostatný platební terminál používající k identifikaci identifikační karty. Vlastní platební terminál se nemusí explicitně identifikovat v rámci přenášených zpráv, neboť je implicitně identifikován přiděleným klientským certifikátem.
- Modrá – Autonomní systémy provádějící transakce na základě předem definovaných událostí, kdy identifikaci účtu provádějí převážně osobním číslem.
Základní popis datového rozhraní pro on-line transakce
Obsah vyměňovaných zpráv na datových rozhraních je popsán formou popisu XML schématu. K dispozici je jak vlastní XML schéma, tak i dokumentace vygenerovaná na základě existujícího XML schématu.
Komunikační vrstva:
- Transportní vrstva : HTTPS, bez stavová
- Datový formát : XML zprávy
- Zabezpečení : SSL 128 bitů, klientský certifikát
Struktura požadavku na provedení transakce v IPS
Obr. 2
| Element/Atribut | Popis |
|---|---|
| terminal_id | Řetězec identifikující terminál požadující provedení on-line transakce. Údaj je povinný pokud aplikace poskytovatele koncentruje více fyzických terminálů. Pokud není element uveden, je pro identifikaci terminálu použito CN z klientského certifikátu, kterým se prokazuje klient vůči serveru. |
| sluzba_id | Identifikátor typu poskytované služby. Identifikátory typů služeb jsou volně definovatelné a přidělované jednotlivým poskytovatelům služeb. Údaj je povinný, pokud poskytovatel na daném terminálu zajišťuje více typů služeb. Předdefinované vyhrazené typy služeb použitelné v návaznosti na typ operace:
UCET_DOBITI – dobití zůstatku na účtu (CR, CRX) |
| lokace | Identifikátor lokace domovského IPS při zapojení do distribuovaného prostředí CLU. Použije se pouze v případě, kdy je terminál schopen vyčíst identifikaci domovské lokace z čipové karty nebo jiného autoritativního zdroje. |
| cislo_cipu | Řetězec reprezentující číslo čipu identifikační karty, interpretace čísla čipu se musí shodovat s interpretací uloženou v IPS nebo pomocí prefixu lze vyjádřit interpretaci právě použitou. Je možné použít prefix "{hex}", "{dec}", "{oct}" a "{bin}" pro hexadecimální, dekadický, oktalový a binární zápis čísla čipu. Vždy je nutné uvádět i nevýznamné nuly zleva a to v závislosti na počtu bajtů unikátního ID identifikační karty. IPS počítá s rozsahem unikátního ID v rozsahu 4-10 bajtů. |
| cislo_uctu | Jednoznačné číslo účtu IPS v rámci jedné instalace (lokace) IPS. Číslo musí vyhovovat kontrolnímu součtu. Algoritmus výpočtu kontrolního součtu je totožný s algoritmem používaným u tuzemských bankovních účtů. |
| os_cislo | Osobní číslo uživatele ověřeného primárním systémem zasílajícím požadavek na transakci. |
| castka | Vlastní požadovaná částka. |
| typ_operace | Typ požadované operace:
ACPT – Potvrzení přijetí odpovědi od IPS terminálem. Potvrzení se neprovádí po operaci DBD a DBP. |
| zivotnost_DBB | Životnost předblokace (DBB) než bude automaticky zrušena systémem IPS. Pokud není element uveden, je životnost dána nastavením u konkrétní služby v IPS. Hodnota se uvádí v sekundách. |
| vsmb | Variabilní symbol, pro potřeby identifikace transakce v návaznosti na systém zasílající požadavek. |
| cas_operace | Časová značka, čas vzniku požadavku na transakci v terminálu. Uvádí se vždy u zahajující operace. V případě navazujících operací se musí shodovat časová značka s časovou značkou zahajující operace, alternativně lze nahradit časovou značku identifikátorem transakce přiděleným zahajující operací. Časovou značku lze uvádět s přesností sekund na šest desetinných míst. Aplikace poskytovatele musí zajistit, aby byly zahajující operace daného terminálu jednoznačně identifikované touto časovou značkou. |
| transakce_id | Identifikátor transakce. Uvádí se v případě provádění navazujících operací k existující transakci nebo předblokaci jako alternativa k časové značce "cas_operace". |
| komentar | Volitelný komentář zasílaný z primárního systému. |
| synchronized | Atribut informuje platební systém, že terminál bude po obdržení odpovědi od platebního systému provádět explicitní potvrzení transakce. Explicitní potvrzení se provádí následným odesláním požadavku s typem operace ACPT a odpovídajícím identifikátorem transakce:
true – synchronní komunikace – IPS po korektním zpracování transakce nastaví tuto transakci jako nepotvrzenou a očekává od terminálu explicitní potvrzení o příjmu odpovědi odeslané z IPS. Potvrzení se neprovádí po operaci DBD a DBP, tzn. netransakční operace. |
Struktura odpovědi na požadavek
Obr. 3
| Element | Popis |
|---|---|
| status | Výsledek zpracování operace v platebním systému:
ACK – Transakce uznána a potvrzena |
| transakce_id | ID transakce v systému vrácené platebním terminálem, pokud status=ACK. |
| chyba | Chybové hlášení zdůvodňující odmítnutí transakce, pokud status=NACK. |
| kod | Kód chyby. |
| zprava | Text chybového hlášení. |
| zůstatek | Informace o zůstatku na účtu klienta, kterou získáte odesláním požadavku se speciálním identifikátorem služby „UCET_ZUSTATEK“. |
| aktualni | Hodnota aktuálního zůstatku účtu. |
| disponibilni | Hodnota disponibilního zůstatku účtu. |
| ucet | Informace k účtu klienta, kterou získáte odesláním požadavku se speciálním identifikátorem služby „UCET_INFO“, viz. samostatný popis datového typu níže. |
Struktura požadavku na výpis detailních informací o účtu klienta
Obr. 4
| Element | Popis |
|---|---|
| cislo_uctu | Jednoznačné číslo účtu IPS v rámci jedné instalace (lokace) IPS vyhovující kontrolnímu součtu. Algoritmus výpočtu kontrolního součtu je totožný s algoritmem používaným u tuzemských bankovních účtů. |
| služby | Informace o povolených službách pro daný účet na daném terminálu. Zatím využíváno pro interní potřebu IPS, popis není součástí této dokumentace. |
| limity | Definovaná omezení k účtu |
| max_zustatek | Maximální povolený zůstatek účtu, uveden pouze pokud je limit nastaven. |
| min_zustatek | Minimální povolený zůstatek účtu. |
| max_db | Maximální povolená částka jedné debetní transakce, uvedena pouze pokud je limit nastaven. |
| max_db_denni | Maximální povolená částka denního obratu na debetu, uvedena pouze pokud je limit nastaven. |
| pocet_cr | Maximální povolený/zbývající počet kreditních operací, uveden pouze pokud je limit nastaven. |
| pocet_db | Maximální povolený/zbývající počet debetních operací, uveden pouze pokud je limit nastaven. |
| osoba | Informace o osobě vlastnící účet. |
| jmeno | Jméno |
| prijmeni | Příjmení |
| os_cislo | Osobní číslo |
| zůstatek | Informace o zůstatcích na účtu klienta, detail viz. popis odpovědi služby „UCET_ZUSTATEK“. |
| platnost_do | Ukončení platnosti účtu k datu včetně. |
Průběžná uzávěrka
V tomto případě se jedná o speciální typ požadavku, který slouží k odsouhlasení obratů a počtu jednotlivých transakcí provedených na konkrétním terminálu od poslední průběžné uzávěrky.
Obr. 5
| Element | Popis |
|---|---|
| terminal_id | Řetězec identifikující terminál požadující provedení on–line transakce. Údaj je povinný pokud aplikace poskytovatele koncentruje více fyzických terminálů. |
| por_cislo | Pořadové číslo uzavírané dávky transakcí. |
| typ_operace | Typ uzávěrkové operace :
|
| pocet_db | Počet debetních transakcí. |
| suma_db | Objem debetních transakcí. |
| pocet_cr | Počet kreditních transakcí. |
| suma_cr | Objem kreditních transakcí. |
Komunikace
Komunikace pomocí HTTPS probíhá metodou Požadavek/Odpověď. V případě transakčních operací je komunikace stavová z důvodu kontroly posloupnosti jednotlivých operací rozpracované transakce. Podpora stavové komunikace umožňuje provádění paralelních transakcí z jednoho terminálu. Ostatní operace jsou bez stavové.
Transakční operace
Transakční operace jsou takové, na základě nichž se v IPS vytvářejí transakce představující finanční pohyby na účtech klientů. Jednotlivé transakční operace lze provádět pro jednu konkrétní transakci pouze ve stanovené posloupnosti. Podle poslední zrealizované operace se transakce nachází v určitém stavu. Případné nedodržení posloupnosti operací je indikováno odmítnutím operace ze strany IPS.
Metody udržování stavové komunikace
Stavová komunikace s transakčním rozhraním explicitně nevyžaduje udržování HTTP session, proto lze identifikovat jednotlivé navazující operace alternativním způsobem. Identifikace se provádí následujícími způsoby:
a) časovou značkou <cas_operace> – značku generuje terminál při první zahajující operaci a stejnou časovou značku používá i v navazujících operacích. Pozn.: nelze využívat pro akceptaci transakcí, viz. níže.
b) přiděleným identifikátorem transakce <transakce_id> – ten obdrží terminál jako odpověď při první operaci. V dalších navazujících operacích pak terminál uvádí pouze element <transakce_id> a časovou značku vynechává.
c) pomocí HTTP session – HTTP klient terminálu udržuje stavovou komunikaci pomocí HTTP session po celou dobu komunikace. Novou posloupnost operací zahajuje terminál vždy operací s novou časovou značkou. O identifikaci navazujících operací se pak klient již nestará a vynechává element <transakce_id> i <cas_operace>. Aplikační server si udržuje poslední přidělené ID transakce v rámci udržovaného HTTP session. Ukončení HTTP session by měl terminál provádět pouze v případě, že se již nebude vracet k ukončené posloupnosti operací. Po ukončení HTTP session se lze vracet k transakci navazující operací identifikovanou pouze způsobem a) nebo b). Session timeout na serveru je nastaven na 35 minut.
Operace debetní transakce
Diagram 1 - posloupnost operací debetní transakce:
Obr. 6
Debetní operaci DB může předcházet tzv. předblokace debetu DBB. Pomocí předblokace se provádí zablokování části disponibilního zůstatku pro zaručenou realizaci budoucí debetní operace dle předpokládané požadované částky debetní transakce. Předblokaci lze provádět opakovaně a navyšovat tak blokovanou částku až na hodnotu disponibilního zůstatku účtu. Blokované částky jsou ze strany IPS po určité době uvolňovány a opakováním předblokace lze prodlužovat dobu, něž dojde k automatickému uvolnění blokace. Nově lze nastavit pomocí elementu <zivotnost_DBB> životnost předblokace, tzn. dobu než bude automaticky zrušena systémem IPS. Pokud není element uveden, je životnost dána nastavením u konkrétní služby v IPS.
Předblokaci lze zrušit operací DBX v plné výši nebo potvrdit operací DB, avšak debetní operace může být provedena maximálně do výše blokované částky.
Storno DBX jako reversní operace pro případ odvolání transakce ze strany terminálu musí být provedeno bezprostředně po provedení příslušné debetní operace nebo předblokace a to v plné výši. Storno DBX jako reklamace je popsáno níže.
Operace kreditní transakce
Diagram 2 - posloupnost operací kreditní transakce:
Obr. 7
Operace kreditní transakce jsou podstatně jednodušší. Po provedení kreditní operace CR lze provést storno CRX jako reversní operaci pro případ odvolání transakce ze strany terminálu. Musí být provedena bezprostředně po provedení příslušné kreditní operace a to v plné výši. Storno CRX jako reklamace je popsáno níže.
Akceptace transakčních operací
Každá transakční operace v IPS vyžaduje potvrzení příjmu ACK odpovědi terminálem. Potvrzování operací zvyšuje bezpečnost komunikace mezi terminálem a IPS a brání tak vzniku nekonzistencí dat, ale potvrzování je pro některé terminály komplikací.
Proto z hlediska komunikace existují pro transakční operace dvě varianty komunikačního protokolu a to v závislosti na nastavení atributu synchronized v elementu <request>. Atribut informuje platební systém, zda bude terminál po obdržení odpovědi od platebního systému provádět explicitní potvrzení operace. Explicitní potvrzení se provádí následným odesláním požadavku s typem operace ACPT a odpovídajícím identifikátorem transakce. Pro akceptaci transakčních operací nelze používat časovou značku, alternativně lze využít HTTP session a akceptovat bez identifikátoru transakce. Nastavení atributu:
- true – synchronní komunikace – IPS po korektním zpracování transakce nastaví tuto operaci jako nepotvrzenou a očekává od terminálu explicitní potvrzení příjmu odpovědi odeslané z IPS. Potvrzení se neprovádí pro operace DBD a DBP, tzn. netransakční operace.
- false – asynchronní komunikace – IPS při korektním zpracování transakce a úspěšném odeslání odpovědi nastaví tuto operaci jako potvrzenou, terminál již nepotvrzuje příjem odpovědi přijaté od IPS.
Pokud nedojde k potvrzení operace v nastaveném čase (dáno parametrem IPS, řádově minuty), IPS automaticky stornuje příslušnou transakci a nebude již možné dále pokračovat v rozpracované transakci.
Prioritní blokace
Prioritní blokace se nevytváří v souvislosti s přímým poskytováním nějaké služby, ale pouze rezervuje-blokuje prostředky pro budoucí úhradu služby (úhradu zpozdného z knihovního systému, úhradu za rezervaci a použití zdroje z rezervačního systému). Proto se v IPS v souvislosti s prioritní blokací nevytváří transakce. Vlastní prioritní blokace ale nezaručuje budoucí úhradu služby, protože pokud suma všech prioritních blokací přesáhne disponibilní zůstatek, transakce bude stejně odmítnuta.
Prioritní blokace je vázána ke konkrétnímu terminálu, proto transakce pro vyrovnání blokované částky musí probíhat z toho samého terminálu, ze kterého byla prioritní blokace vytvořena. Prioritní blokace musí být prováděna kumulativně za všechny dlužné částky, tzn. pro daný terminál existuje pouze jedna prioritní blokace. Opakovaným prováděním prioritní blokace se částka může navyšovat nebo snižovat a navýšení prioritní blokace může být prováděno bez kontroly nebo s kontrolou na limity (disponibilní zůstatek) v závislosti na oprávnění terminálu. Nastavením prioritní blokace na hodnotu 0 „nula“ dojde ke zrušení prioritní blokace z daného terminálu.
Vyrovnání blokované částky se provede v nové transakci operací DB. Pokud PS zjistí, že k danému terminálu existuje prioritní blokace a lze zrealizovat transakci s ohledem na disponibilitu účtu, zrealizuje transakci a o příslušnou částku sníží hodnotu prioritní blokace, avšak maximálně o hodnotu existující prioritní blokace. V případě nedostatečné disponibility účtu je transakce odmítnuta.
Pro prioritní blokace platí následující:
- Institut prioritní blokace je primárně určen pro dlouhodobou blokaci finančních prostředků na účtu klienta PS, nevytváří se na jejím základě žádná transakce v PS. Tzn. provozní systém si tímto rezervuje prostředky na budoucí úhradu své pohledávky vůči klientovi. Prioritní blokace PS automaticky nestornovává.
- Pro každý terminál a účet může existovat nejvýše jedna prioritní blokace.
- Prioritní blokaci lze zvyšovat i snižovat. Blokace se provádí na konkrétní hodnotu, nikoliv inkrementálně, tzn. že provozní systém si musí provádět kumulaci všech svých pohledávek.
- Zrušení prioritní blokace se provede nastavením prioritní blokace na hodnotu 0 „nula“.
- Existují dva typy prioritní blokace, blokace s kontrolou a bez kontroly na disponibilní zůstatek. Určuje se uvedeným typem služby.
- Při realizaci DB transakce na účtu, ke kterému má terminál vytvořenu prioritní blokaci se přednostně umořuje prioritní blokace. Tzn. že PS systém provede v rámci DB transakce snížení hodnoty prioritní blokace o hodnotu DB transakce a vlastní transakci v jednom kroku. Nekontrolují se limity na provedení DB operace, pouze nesmí být překročen minimální povolený zůstatek účtu.
... další specifikace a podrobnosti pouze na vyžádání u provozovatele IPS.
