Transakční rozhraní interního platebního systému IPS

Úvod

Tento dokument popisuje standardní rozhraní pro ověřování kreditních a debetních transakcí interního platebního systému. Níže popsaná nová verze rozhraní zachovává zpětnou kompatibilitu s předchozí verzí transakčního rozhraní. Nové rozhraní rozšiřuje funkcionalitu a možnosti aplikací připojených k internímu platebnímu systému.

Použité zkratky a pojmy

Zkratka/Pojem	Význam v tomto textu
HTTPS	Přenosový protokol pro přenos hypertextových zpráv se zabezpečením SSL.
IPS	Interní platební systém.
LDAP	Adresářový server pro ověřování uživatelů.
VSMB	Variabilní symbol.
Platební zařízení	Platební terminál, pokladní terminál nebo aplikace poskytovatele služeb připojená k IPS a poskytující služby v rámci IPS.
CLU	Clearingový uzel zajišťující vzájemné zúčtování plateb mezi platebními systémy IPS. Jedná se o nadstandardní rozšíření IPS.

Koncepce řešení

On-line komunikace s IPS je založena na výměně zpráv metodou Požadavek/Odpověď, přičemž 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 v následujících kapitolách. Každé platební zařízení se bude k IPS připojovat prostřednictvím HTTPS protokolu a za tímto účelem bude vybaveno odpovídajícím klientským certifikátem prokazujícím identitu připojovaného místa. Pro potřeby šifrování doporučujeme 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 takový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 celého 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 dle vnitřní směrnice 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.

Popis

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.

Datové 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.

Popis rozhraní

Komunikační vrstva

Transportní vrstva : HTTPS, bez stavová

Datový formát : XML zprávy

Zabezpečení : SSL 128 bitů, klientský certifikát

Požadavek

Požadavek na provedení transakce v systému pro vedení interních osobních účtů (autorizace plateb).

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.

Odpověď

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