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 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. 1

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) UCET_VYBITI – vybití zůstatku účtu v nedisponibilním stavu (DB, DBX) UCET_CERPANI – výdej hotovosti na pokladně (DBB, DB, DBX) UCET_REKLAMACE – reklamace existující transakce (CRX, DBX) UCET_ZUSTATEK – informace o zůstatcích na účtu (DBD) UCET_INFO – informace o parametrech účtu (DBD) BLOKACE_LIM_ANO – prioritní blokace s kontrolou limitů (DBP) BLOKACE_LIM_NE – prioritní blokace bez kontroly limitů (DBP)
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. DB – Debetní operace – odepsání částky z účtu. DBD – Pasivní debetní operace sloužící k ověření, zda se požadovaná částka pohybuje v rámci disponibilního zůstatku účtu. DBB – Debetní operace – předblokace požadované částky na daném účtu, přičemž předblokaci lze opakovaně navyšovat až na hodnotu disponibilního zůstatku. Předblokaci lze zrušit operací DBX v plné výši nebo potvrdit operací DB, avšak maximálně do výše blokované částky. DBP – Prioritní debetní blokace – slouží k rezervaci prostředků na účtu pro přednostní uspokojení budoucí debetní transakce. Tato blokace může být pouze jediná platná pro každý terminál a účet. Každá následující prioritní blokace revokuje předchozí prioritní blokaci pro daný terminál. Prioritní blokaci lze průběžně zvyšovat i snižovat a snížením na nulovou hodnotu dojde k jejímu zrušení. Podrobnosti viz. odst. 3.3.2. DBX – Storno debetní operace – storno odepsané nebo blokované částky z osobního účtu. Storno jako reversní operace pro případ odvolání transakce v primárním systému musí být provedeno bezprostředně po provedení příslušné debetní operace nebo předblokace a to v plné výši. Storno se využívá i pro reklamaci, viz. odst. 3.3.1. CR – Kreditní operace – připsání částky na osobní účet. CRX – Storno kreditní operace – storno připsané částky na osobní účet. Storno jako reversní operace pro případ odvolání transakce v primárním systému musí být provedeno bezprostředně po provedení příslušné kreditní transakce. Storno se využívá i pro reklamaci, viz. odst. 3.3.1.
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. false – asynchronní komunikace – IPS při korektním zpracování transakce nastaví tuto transakci jako potvrzenou, terminál již nepotvrzuje příjem odpovědi přijaté od IPS.

Struktura odpovědi na požadavek

Obr. 2

Element	Popis
status	Výsledek zpracování operace v platebním systému: ACK – Transakce uznána a potvrzena NACK – Transakce odmítnuta. Systém vrací chybu s chybovým kódem a zprávou zdůvodňující odmítnutí transakce v systému pro vedení osobních účtů.
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.

Detailní informace o účtu klienta

Obr. 3

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ě.