Technická specifikace platební brány

Cílem zavedení dynamického nákupního systému (dále jen “DNS”) je vytvořit systém, ve kterém budou příjemci plateb ve volné soutěži mezi dodavateli zařazenými v DNS zajišťovat platební brány pro své potřeby, přičemž všechny tyto platební brány budou standardizovány v rozsahu, který je uveden v zadávací dokumentaci DNS.

Cílem vytvoření tohoto systému je z hlediska příjemců integračně a implementačně jednoduchá platební brána, umožňující platbu subjektům veřejné správy, vč. subjektů založených či zřízených (např. právním předpisem).

Platba bude možná několika platebními způsoby, které jsou z hlediska výběru poplatku zcela totožné:

• platba debetní platební kartou (Visa, MasterCard, Maestro, atd.),
• platba kreditní platební kartou (Visa, MasterCard, atd.),
• bankovním převodem z internetového bankovnictví banky občana,
• online bankovní platbou z podporovaných internetových bankovnictví,
• elektronické peněženky (typicky Visa Checkout, Masterpass, Google Pay a Apple Pay),  
• v budoucnu mohou být přidány další platební metody dle vývoje možností trhu.

Platbu bude možné provádět jak z webového prohlížeče (desktop, tablet, mobil), tak z mobilní aplikace platební brány a spolupracujících platebních providerů.

Na účet příjemce bude připsána platba v plné výši, poplatky za transakci budou vyúčtovány zpětně podle uskutečněných transakcích za předchozí měsíc.

Názvy rolí jsou uváděny promiscue v jednotném či množném čísle.

Příjemci plateb (dále též jen “příjemci”) jsou subjekty veřejné správy, vč. subjektů založených či zřízených (např. právním předpisem), kteří v zavedeném DNS uzavřou smlouvu s poskytovatelem, či více poskytovateli na užívání platební brány či více platebních bran. Příjemci plateb mohou být zejména:

• Správní úřady,
• Ústřední orgány státní správy,
• Územní orgány státní správy v přenesené působnosti,
• Ostatní státní orgány (např. státní fondy),
• Orgány územně samosprávných celků,
• Příspěvkové organizace,
• Státní podniky,
• Organizace založené zákonem

Současně jde o subjekt, který nabízí platbu kartou a kdo definuje parametry transakce.

Provozovatelé platebních bran (dále též jen “provozovatelé”) a v konečném důsledku realizátoři plateb prostřednictvím platebního kanálu. Většina platebních metod bude prováděna v téměř reálném čase, tzn. příjemce i plátce mají o úspěchu platby informaci např. během 30 s od provedení platby.

Některé platby musí být možné provádět pouze některými platebními kanály (typicky platba daní či vysokých částek nad 30.000 Kč). O případném omezení platebních kanálů rozhodne vždy příjemce platby.

Subjekty provádějící převod finančních prostředků příjemcům plateb (např. úhrada správního poplatku, parkovného apod.) prostřednictvím platebních bran provozovaných na základě DNS.

Příjemcům plateb bude k dispozici aplikace pro vyúčtování poplatků. Provozovatel brány provede pravidelné vyúčtování poplatků jednotlivým příjemcům v pravidelných intervalech vždy za předchozí měsíc.

Tuto aplikaci provozuje každý Provozovatel platební brány pro svou vlastní bránu.

Funkčnost aplikace vyúčtování poplatků:

• zaslání elektronického podrobného vyúčtování a daňového dokladu příjemce
• uložení vyúčtování do platební brány prostřednictvím API platební brány.
• Vyúčtování bude poskytnuto ve strojově čitelném souboru v následujících formátech:
  • ABO (bankovní formát pro výměnu platebních zpráv) a
  • CSV a
  • TAB delimited.

Aplikace vyúčtování poplatků nebude mít žádné UI rozhraní a bude komunikovat s ostatními systémy a příjemci plateb pouze prostřednictvím API a případně i prostřednictvím datové schránky.

Plátci nyní platí příjemcům hotově, kolky, převodem z účtu či složenkou.

Příjemce plateb má právo rozhodnout, za které služby bude možné zaplatit (rovněž) prostřednictvím platební brány. Toto rozhodnutí je rozhodnutí plně v pravomoci příjemce plateb. Z užívání platební brány nesmí plynout žádná výhrada, musí tedy být i nadále možné zaplatit hotově, kolkem či převodem z účtu stejně jako doposud ty služby, které bude možné zaplatit i prostřednictvím platební brány.

Technický popis požadavků na jednotné API je popsán v kapitole Technický popis rozhraní.

Požadavek na platbu iniciuje příjemce.

1. Je to typicky žádost o poskytnutí služby ze strany státu, např. výpis z katastru nemovitostí, kde si tuto službu občan objedná, ale částku a její zaplacení iniciuje příjemce.
2. Jiná forma je např. požadavek na zaplacení pravidelného poplatku, např. roční poplatek za odvoz komunálního odpadu.

Požadavek na platbu může být doručen a prezentován různými způsoby. Možné příklady jsou:

• tlačítko na webové stránce
• formulář na webové stránce (před výběr parametrů platby, typicky platební kanál)
• zkrácený odkaz v emailu či datové zprávě
• QR kód

V konečném důsledku se však jedná o speciálně vytvořené URL (odkaz) na platební bránu popisující parametry požadované platby. Podobnosti viz 4.3 Požadavek na platbu.

Plátce je pomocí prohlížeče přesměrován na platební bránu. Zde se zobrazí prostředí brány s předvyplněnými údaji k platbě, dle parametrů seznam kanálů k provedení platby.

Po vybrání platebního kanálu je spuštěna platba vybraným platebním kanálem, specifickými parametry podle vybraného platebního kanálu.

Zadavatel požaduje, aby brány provozované na základě tohoto DNS měly jednotné UX (user experience). Bližší podmínky pro UX jsou uvedeny v obchodních podmínkách ZD.

Po vybrání platebního kanálu je spuštěna platba vybraným platebním kanálem, specifickými parametry podle vybraného platebního kanálu. Tuto část zajišťuje provozovatel platební brány a pokud je to technicky možné, je v UX Design systému Portálu občana.

Typický případ, kdy není možné provést samotnou platbu v UX platební brány je platba prostřednictvím internetového bankovnictví banky, které probíhá v UX banky.

Provozovatel platební brány pro kanál specifickým způsobem předá informace o úspěchu či neúspěchu platby platební bráně.

Platební brána zpracuje specifické návratové údaje od platebního kanálu, sjednotí je a převede do jednotného formátu platební brány a výsledek platby předá na cílové URL (typicky web aplikaci příjemce).

Součástí návratových hodnot je původní požadavek na platbu, výsledek transakce, číslo transakce v platební bráně a kontrolní součet (hash). Součástí návratové informace bude také identifikace osoby, jejímž prostředkem bylo zaplaceno (protože nemuselo jít o tutéž osobu, jaká byla při definici výměru platby).

Zde dojde k potvrzení úspěchu či neúspěchu platby a web aplikace vlastní logikou rozhodne o dalším postupu či předání informace aplikacím příjemce (ve schématu bod 6.)

Evidence transakce a poplatku za transakci se zaeviduje v systému provozovatele platební brány a v pravidelných intervalech (minimálně 1xměsíčně) dojde k vyúčtování poplatků.

Vyúčtování poplatků bude mít na starosti pravidelné vyúčtování poplatků jednotlivým příjemcům v pravidelných intervalech vždy za předchozí měsíc.

Aplikace bude provozována provozovatelem platební brány.

Funkčnost aplikace vyúčtování poplatků:

• zaslání elektronického podrobného vyúčtování a daňového dokladu příjemci
• uložení vyúčtování do platební brány prostřednictvím API platební brány

Aplikace vyúčtování poplatků nemusí mít žádné UI rozhraní (je volitelné) a bude komunikovat s ostatními systémy a příjemci pouze prostřednictvím API a zasláním přes datovou schránku nebo email.

Příjemce se může kdykoliv platební brány zeptat na stav proběhlé transakce vyvolané příjemcem. Je to vhodné například pro dávkové zpracování plateb v aplikaci příjemce.

Uvedením přímé adresy https://platebnibrany.gov.cz/ se zobrazí základní informace o platební bráně pro veřejnost a pro veřejnou správu.

Tuto stránku bude provozovat Ministerstvo vnitra a její vytvoření není předmětem tohoto DNS.

Řízení přístupu konkrétních osob k platební bráně je pomocí autentifikace provozovatele platební brány.

Před začátkem používání se musí příjemce plateb poprvé přihlásit k platební bráně a nastavit parametry platební brány a získat údaje potřebné pro napojení vlastních systémů k platební bráně. To provede z titulní stránky platební brány.

Pro registraci, změny nastavení platební brány či ukončení používání platební brány se musí příjemce k platební bráně přihlásit pomocí autentifikace provozovatele platební brány.

První přihlášení k platební bráně zahájí registrační proces. Registrační proces vyžaduje uvedení kontaktních údajů, které nejsou k dispozici v základních registrech a uvedení cílových bankovních účtů, kam se mají posílat peníze.

Přihlášení příjemce plateb je provedeno pomocí autentifikace provozovatele platební brány, kterým příjemce prokáže právo vystupovat za plátce.

Administrace platební brány umožní změny parametrů, změny, smazání a doplnění cílových bankovních účtů pro platby, přegenerování komunikačních parametrů API, nahrání loga příjemce atd.

V administraci platební brány jsou uvedeny parametry API rozhraní a další instrukce potřebné pro nasazení brány, resp. odkazů s parametry platby na web příjemce platby.

Vložení HTML kódu s parametry z administrace platební brány. Do stránky bude možné vložit odkaz či funkcionalitu platební brány pro zaplacení v různých formách: tlačítko či tlačítka, formulář, popup či iFrame.

Nasazení bude jednoduché, stačí zkopírovat HTML kód pro vybranou formu z administrace platební brány či vzor HTML kódu s parametry integrovat do web aplikace příjemce platby.

K dispozici budou také open-source knihovny spravované provozovatelem brány, které zajistí:

• Generování HTML kód a URL s parametry pro požadavek na platbu
• Generování a validaci kontrolních součtů odesílaných i přijatých požadavků
• Komunikaci s API platební brány
  • Výpis transakcí
  • Výpis zúčtování
  • Kontrola jednotlivých transakcí

Bude možné zrušit všechny registrace k platební bráně. Pro všechny registrace příjemce může zrušit příjemce

Požadavek na platbu může iniciovat pouze řádně registrovaný příjemce plateb. Jakýkoliv neplatný požadavek na platbu bude bránou odmítnut se srozumitelným popisem pro plátce a zalogováním údajů pro následnou analýzu.

Typické platby

• Platba pevného správního poplatku libovolnou platební metodou.
• Platba procentního poplatku libovolnou platební metodou.
• Platba za jakoukoliv službu občanem či firmou

Požadavek na platbu může být plátci doručen a prezentován různými způsoby. Možné příklady jsou:

- tlačítko na webové stránce

- formulář na webové stránce (před výběr parametrů platby, typicky platební kanál)

- zkrácený odkaz v emailu či datové zprávě

- QR kód

Příjemce iniciuje požadavek na platbu pomocí některé z forem uvedených výše.

Parametry požadavku na platbu předávané platební brány jsou:

• ID příjemce v systému platební brány
• Variabilní symbol (ID úředního úkonu, např. ČJ či variabilní symbol platby)
• Požadovaná částka
• Měna
• Cílový účet, kam mají být peníze připsány (číslo zaregistrovaného účtu nebo jeho ID v systému platební brány)
• Jméno, příjmení plátce (volitelné, pouze evidenční údaj neomezující provést transakci jinou osobu)
• Splatnost (obvykle ihned)
• Omezení platebních metod (nepovinně, např. zakázat plat. karty)
• Volitelný volný text (pouze evidenční údaj pro následné dodatečné zpracování v systémech příjemců plateb, taktéž tento text bude použit jako návrh textu platební transakce u banky klienta)
• Kontrolní součet (hash)

Pokud se poplatník rozhodne zaplatit, zahájí platbu klikem na platební tlačítko či vyplněním některé z forem platební brány (tlačítko, formulář, scan QR kódu z mobilu atd).

Poplatník si vybere platební metodu, projde následnou transakcí podle vybrané metody (např. pro platební kartu zadáním údajů o kartě a 3D Secure).

Brána po dokončení platebního procesu zasílá zpětné info o transakci (HTTPs callback od brány) anebo se informační systém příjemce pravidelně ptá na stav transakce (dle dokumentace).

Výsledkem je úspěšná transakce (= peníze na účtu nebo na cestě, pozitivně ověřená a schválená platba) anebo neúspěšná transakce.

Peníze jsou na požadované účty zaslány každý den se zpožděním nejdéle 10 pracovních dní. Zasílána je jedna každá jednotlivá transakce od klienta s odpovídajícím variabilním symbolem.

Jednou měsíčně je zasláno elektronické vyúčtování jednotlivých plateb.

Může nastat situace, kdy příjemce platby vrátí platbu zpět poplatníkovi. Obvykle při chybném úředním postupu či zaplacení špatného poplatku.

V souladu se zákonem č. 634/2004 Sb. § 7 umožní platební brána vrácení poplatku stejným způsobem, jakým byl zaplacen, anebo jiným způsobem dle dohody s poplatníkem. Náklady vrácení nese příjemce platby.

IS příjemce je o tom informován HTTPs callbackem od brány či pravidelných PULL dotazem z IS systému na zrušené transakce.

Pokud plátce reklamuje platbu, je ze strany provozovatele platební brány zahájen obvyklý reklamační proces 4.10.1. Je to výjimečná situace. V případě uznané reklamace příjemce platby platbu vrací.

Plátce dostane potvrzení o úspěchu platby ihned po potvrzení branou v rámci aktuálně prováděné transakce. Formou notifikace přes notifikační server dostane formální potvrzení platby a zaplatí za zpoplatněný úkon. Pokud bude notifikační kanál k danému poplatníkovi otevřen. Musíme respektovat jeho právo, že nemusí chtít zadat své údaje pro účely notifikace.

Následovat bude potvrzení o dokončení úkonu ze strany příjemce platby.

Pokud byla platba neúspěšná, je zaslána notifikace a upozornění, že k úřednímu úkonu nedošlo. Ideálně s linkem na okamžité zaplacení neúspěšné platby.

Souhrnné a analytické reporty pro příjemce.

V první verzi základní řešení na straně platební brány.

Příjemce bude data pro reporting zasílat na sdílený analytický/datový server GOV.CZ, který bude reporty poskytovat centrálně ve formátu Opendata, zaregistrovaném do Národního katalogu otevřených dat veřejné správy ČR (dále jen “NKOD”).

Souhrnný a podrobný přehled poplatků za jednotlivé transakce, seznam vystavených faktur k zaplacení poplatků bude zajišťovat aplikace vyúčtování poplatků.

Za provoz je zodpovědný provozovatel platební brány. Do jeho zodpovědnosti spadají

• Kontrola a analýza neúspěšných transakcí
• Anti-fraud mechanismy
• Vyřizování reklamací plateb ze strany plátců i příjemců plateb
• Provoz a dostupnost služeb

Plátce kontaktujte provozovatele brány přes veřejný formulář nebo infolinku s popisem problému. Následné řešení je už formou privátní online či telefonické komunikace dle standardů platebních společnosti.

Příjemce plateb provádí reklamaci z administrace platební brány online formulářem. Tzn. zahájení je již s autorizovaným uživatelem. Následná komunikace může probíhat nadále online, anebo telefonicky.

Nedílnou částí řešení je přehledná dokumentace pro integraci platební brány a příklady implementace.

—

Pozn. zadavatele: požadavky této části budou předmětem ověření v popisu brány, která má být předmětem dodávky

—

API sdílené platební brány používá architektonický vzor REST API, dokumentované ve formě HTML popisu a OpenAPI Specification (dříve Swagger).

API bude dostupné na URL <adresa.platebni.brany>/api/, kde jsou další endpointy API. API je dostupné pouze před HTTPS protokol.

K API přistupuje klient platební brány – příjemce platby (dále klient PB)

Veškeré časy v API jsou uváděny pouze a výhradně v UTC, ve formátu YYYY-MM-DDThh:mm:ss.sssZ , který je v souladu s ISO 8601.

Příklad: 2012-04-23T18:25:43.511Z

Veškeré kódování znaků je UTF-8.

Používá se protokol OAuth2.0, metoda klientské autentizace dle RFC http:%%//%%tools.ietf.org/html/rfc6749#section-4.4

Při registraci do platební brány příjemce plateb dostane své unikátní přístupové údaje pro API: ClientID a ClientSecret.

Pomocí přístupových údajů si klient PB si požádá o dočasný přístupový klíč - Bearer token, který má platnost 30 minut.

POST /api/oauth2/token

HTTP Request

HTTP Response

{

"tokenType":"bearer",

"accessToken":"DKFJD…..asdfkdj……fadsf",

"expires":"2012-04-23T18:25:43.511Z"

}

<a href="odkaz_na_platebni_branu">Zaplaťte zde</a>

nebo <a href="odkaz_na_platebni_branu"><img src=”odkaz_na_button_sdilene_platebni_brany” alt=”Zaplaceni transakce online”></a>

Odkaz na platební bránu s instrukcemi k odeslání se vytvoří takto:

Validace obsahu požadavku a odpovědi je vypočten na základě

• odesílaných dat: tím je zajištěna kontrola, že obsah jednotlivých parametrů nebyl změněn při odeslání směrem k platební bráně
• ClientSecret: unikátní klíč příjemce, který se v rámci dat neposílá a je použit na vytvoření kontrolního součtu (hashe). Tím se umožní kontrola, že požadavek pochází od daného deklarovaného příjemce.

Výpočet Hash:

1. setřídit všechny parametry určené pro výpočet hash (viz tabulka výše), podle abecedy. Pokud parametr neobsahuje hodnotu, je stejně zařazen do výpočtu
2. vytvořit řetezec spojením hodnot jednotlivých parametru v pořadí z bodu 1., za hodnotu se přidá jako oddělovač znak | (ASCII 124). Řetezec se ukončí hodnotou ClientSecret.
   výpočet: hodnota parametru Amount + znak | + hodnota parametru BankAccountID + znak | + hodnota parametru DueDate ….. atd … | hodnota ClientSecret.
3. Pokud parametr neobsahuje žádnou hodnotu, následují dva znaky | za sebou: ||
4. Vytvořeny řetězec je zahashován funkcí algoritmem SHA-512, a poté zakódován pomocí BASE64
5. Výstup BASE64 funkce je hodnotou parametru Hash v requestu

Po dokončení uživatelské interakce s klientem platební brána přesměruje prohlížeč klienta na URL uvedené v parametru DestUrl požadavku na platbu, s těmito parametry.

V návratovém URL se uvedou všechnu parametry z požadavku na platbu, s výjimkou DestUrl, a stejným algoritmem je spočítám i kontrolní součet v parametru hash.

Kontrolní součet do parametru Hash je spočítám stejně, jako u požadavku na platbu, včetně ClientSecret klienta, s použitím parametru z tabulky návratových parametrů.

POST /api/transaction/status/transactionId

HTTP Request headers

HTTP Response

{

"TransactionId": "",

"PaymentStatus": "",

"ErrorStatus": "",

"ErrorDescr": "",

"MerchantID": "",

"MerchantOrderId": "",

"Amount": "",

"Currency": "",

"BankAccountId": "",

"CustomerName": "",

"DueDate": "",

"DisablePaymentMethods": "",

"AddInfo": "",

"Created":””

"Hash": ""

}

Hodnoty a význam atributů jsou popsány v Odpověď platební brány s výsledkem platby.