qr-platba.cz - Specifikace formátu

Specifikace formátu | QR Platba

Qr-platba.cz Spined HTML

Specifikace formátu | QR Platba HomeGenerátor QR PlatbyPro uživatelePro výstavcePro vývojářeSpecifikace formátuGenerátor QR PlatbySpecifikace RESTful APIValidátor SPAYD řetězceKnihovny na GitHubuGrafický manuálKontakt Specifikace formátu Popis formátu QR platba Formát řetězce je navržen tak, aby byl kompaktní co se velikosti obsažených dat týče. Výhodou navrženého formátu je relativně dobrá lidská čitelnost a potenciální rozšiřitelnost o specifické atributy. Řetězec může obsahovat libovolné znaky ze znakové sady ISO-8859-1 (znaková sada pro binární QR kód). Pro efektivní uložení do QR kódu doporučujeme sestavit řetězec tak, aby obsahoval pouze následující znaky: 0–9 A–Z [pouze velká písmena] mezera $, %, *, +, -, ., /, : Při zachování znaků výhradně z uvedené množiny bude použit tzv. alfanumerický formát QR kódu. Množina znaků používaná v klíčích a řídících strukturách navrženého formátu je proto volena právě z této množiny tak, aby nebylo zabráněno dosažení maximální možné efektivity uložení platebních informací do QR kódů. Bude-li v hodnotě kteréhokoli pole použit znak z jiné množiny, než je uvedena výše, bude použit tzv. binární formát QR kódu. QR kód by měl být pro tištěná media generován s úrovní kontroly chyb M (obnovitelnost 15%). Řetězec je vždy zahájen fixní hlavičkou SPD*. Následuje verze protokolu (dvě čísla oddělená tečkou) ukončená hvězdičkou, např. 1.0*. Následně  řetězec obsahuje jednotlivé atributy platby ve formátu: ${klíč}:${hodnota}* Tedy klíč je od hodnoty oddělen dvojtečkou, hodnota je zakončena hvězdičkou. Pole ${hodnota} nesmí obsahovat hvězdičku (může být v hodnotě zakódována jako %2A, jak je popsáno níže). ${klíč} Klíč daného atributu je vždy zapsán velkými znaky z množiny znaků [A-Z-]. Seznam přípustných klíčů (základní sada atributů) je uveden v Tabulce 1. Formát může být rozšířen o proprietární klíče, které mají např. lokální význam pro konkrétní lokalitu nebo instituci. Sada již nyní uvažovaných rozšiřujících klíčů je uvedena v Tabulka 2. Takovéto klíče jsou uvozeny znaky X-. ${hodnota} Hodnota daného atributu může obsahovat libovolné znaky, ale musí být zároveň v přípustném formátu pro dané pole – viz. popis formátu hodnoty v Tabulce 1 a Tabulce 2. Hodnota nesmí být obklopena bílými znaky (tj. za “:” a před “*” nesmí být bílé znaky) a nesmí obsahovat znak * (hvězdička). Hodnota může obsahovat znak : (dvojtečka). Hodnota může obsahovat speciální znaky kódované pomocí URL kódování. Díky tomuto mechanismu je možné kódovat libovolné znaky z UTF-8, hvězdičku je tedy možno do hodnoty zahrnout pomocí zápisu %2A. Pokud bude hodnota obsahovat více znaků, než připouští formát, bude zpracován pouze formátem specifikovaný počet znaků zleva, ostatní budou ignorovány. Pozn.: Podpora pro kódování speciálních znaků je základním parametrem typově podobných formátů. V principu existuje několik přístupů, např. HTML entity, back-slashing nebo touto specifikací zvolené URL kódování.   Tabulka 1 – základní parametry Klíč Povinný Délka Formát Hodnota Příklad zápisu klíče a hodnoty ACC ANO Max. 46 znaků (IBAN+BIC) IBAN, BIC Identifikace protistrany, která je složena ze dvou komponent oddělených znaménkem + Tyto komponenty jsou: číslo účtu ve formátu IBAN identifikace banky ve formátu SWIFT dle ISO 9362. Druhá komponenta (SWIFT) je přitom volitelná. ACC:CZ5855000000001265098001+RZBCCZPP* … a nebo (varianta bez čísla BIC): ACC:CZ5855000000001265098001* ALT-ACC NE Max. 93 znaků (2x pole ACC + oddělovač) IBAN, BIC Seznam alternativních účtů k výchozímu účtu danému hodnotou ACC. Jednotlivé záznamy mají stejný formát jako pole ACC a jsou odděleny čárkou. Klientské aplikace mohou tento seznam použít pro zobrazení volby, na který účet se má platba odeslat, např. za účelem optimalizace výše poplatků za převod. Pro potřebu zachování akceptovatelné datové hustoty dat na mediu typu QR kód se do pole nedoporučuje vkládat více než 2 alternativní čísla účtu. ALT-ACC:CZ5855000000001265098001+RZBCCZPP, CZ5855000000001265098001* AM NE Max. 10 znaků Pozn.: Odpovídá částce 9 999 999,99 Desetinné číslo. Max. 2 desetinné cifry. Tečka jako oddělovač desetinných míst. Výše částky platby. AM:480.55* CC NE Právě 3 znaky ISO 4217 – délka 3 znaky, velká písmena. Měna platby. CC:CZK* RF NE Max. 16 znaků Celé číslo Identifikátor platby pro příjemce. RF:1234567890123456* RN NE Max. 35 znaků Všechny znaky z povolené množiny mimo ‘*’ Jméno příjemce. RN:PETR DVORAK* DT NE Právě 8 znaků ISO 8601, tj. datum ve formátu YYYYMMDD. Pouze numerické znaky. Datum splatnosti. DT:20121231* PT NE Max. 3 znaky Všechny znaky z povolené množiny mimo ‘*’ Typ platby PT:P2P* MSG NE Max. 60 znaků Všechny znaky z povolené množiny mimo ‘*’ Zpráva pro příjemce. MSG:PLATBA ZA ELEKTRINU* CRC32 NE Právě 8 znaků Znaky z množiny: [A-F0-9] Kontrolní součet. Hodnota vznikne spočítáním CRC32 řetězce bez hodnoty CRC32 a převedením této číselné hodnoty do hexadecimálního zápisu. Princip vypočítání CRC32 (zajištění jednoznačnosti reprezentace pro výpočet CRC32): Použijí se všechny atributy mimo atributu CRC32 Sestaví se kanonický řetězec tak, že převezme hlavičku („SPD*1.0*”), ostatní atributy se setřídí dle klíče a sekundárně dle hodnoty, v tomto pořadí se zakódují do řetězce dle specifikace a sestaví se tak základ pro počítání CRC32 Výsledek se převede do šestnáctkové soustavy CRC32:1234ABCD* NT NE Právě 1 znak P (= phone) E (= e-mail) Identifikace kanálu pro zaslání notifikace výstavci platby. Poznámka: odesílání notifikací se řídí podle podmínek jednotlicých bank, nicméně doporučuje se odesílat v okamžiku blokace prostředků na účtu plátce. NT:P – notifikace bude zaslána formou SMS NT:E – notifikace bude zaslána formou e-mailu NTA NE Max. 320 znaků pro NT:P +N[12] pro NT:E e-mailAddress[64] @domainName[255] Telefonní číslo v mezinárodním nebo lokálním vyjádření nebo E-mailová adresa NTA:00420123456789 NTA:+420123456789 NTA:123456789 NTA:ales.dynda@abc.cz   Tabulka 2 – Rozšířené atributy pro platební styk v rámci ČR Rozšíření pro České podmínky obsahuje speciální atributy pro identifikátory bankovních plateb. Klíč Povinný Délka Formát Hodnota Příklad zápisu klíče a hodnoty X-PER NE Max. 2 znaky Celé číslo Min. hodnota 0 (neopakovat).Max. hodnota 30 Počet dní, po které se má provádět pokus o opětovné provedení neúspěšné platby (z důvodů např. nedostupných prostředků na účtu příkazce). X-PER:7* X-VS NE Max. 10 znaků Celé číslo Variabilní symbol X-VS:1234567890* X-SS NE Max. 10 znaků Celé číslo Specifický symbol X-SS:1234567890* X-KS NE Max. 10 znaků Celé číslo Konstantní symbol X-KS:1234567890* X-ID NE Max. 20 znaků. Všechny znaky z povolené množiny mimo ‘*’ Identifikátor platby na straně příkazce. Jedná se o interní ID, jehož použití a interpretace závisí na bance příkazce. Může být použito například jako identifikace e‑commerce platby, nebo pro statistické či marketingové účely. X-ID:ABCDEFGHIJ1234567890* X-URL NE Max. 140 znaků Všechny znaky z povolené množiny mimo ‘*’ URL, které je možno využít pro vlastní potřebu X-URL:HTTP://WWW.SOMEURL.COM/*   Tabulka 3 – Atributy, které jsou schopny zpracovat všechny banky v ČR pro tuzemský platební styk Uvedené atributy je schopna zpracovat kterákoliv banka v ČR v rámci tuzemského platebního styku. Atributy, které nejsou v této tabulce uvedené, jsou schopny zpracovat pouze některé banky. Více informací je k dispozici vždy na dotaz u konkrétní banky. Klíč Zpracují všechny banky ACC ANO, vždy jen jeden účet ALT-ACC AM ANO CC ANO, pro tuzemský platební styk pouze CZK DT ANO MSG ANO X-VS ANO X-SS ANO X-KS ANO   Ukládání a sdílení řetězce Formát definuje pro potřeby klientských aplikací vlastní příponu souboru pro případ uložení a vlastní MIME type. MIME-type: application/x-shortpaymentdescriptor Přípona souboru: *.spayd   Příklad Zpráva: SPD*1.0*ACC:CZ2806000000000168540115*AM:450.00*CC:CZK*MSG:PLATBA ZA ZBOZI*X-VS:1234567890 QR kód: QR platba příklad © 2018 QR Platba, e-mail ↑ Responsive Theme powered by WordPress