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.
Obr. 1
Typické schéma připojení platebních zařízení
V základním blokovém schématu jsou barevně odlišena jednotlivá platební zařízení podle charakteru komunikace platebního zařízení s IPS.
- Ž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
Obr. 6
