Funkce pmAPI

2.1. Transakce

2.1.1. Stav transakce

Transakce při procházení svým životním cyklem mohou nabývat mnoha různých stavů. Po vytvoření může být transakce úspěšně autorizována, nebo zamítnuta. Zamítnutí může zapříčinit mnoho různých důvodů. Např. nedostupnost autorizačního serveru, nedostatek prostředků na kartě plátce, exspirovaná platební karta… Úspěšně autorizované transakce poté putují do zúčtování. Autorizované nezaúčtované i zaúčtované transakce mohou být reverzovány a opětovně vráceny ke zpracování.

Transakce může nabývat stavů:

• processing - ve zpracování
• deny - zamítnuto
• authorized - autorizováno/nezaúčtování
• processed - autorizováno/zaúčtováno
• reversed - reverzováno

Stavy transakce

2.1.1.1. Zjištění stavu transakce payment/state

Metoda sloužící ke zjištění aktuálního stavu transakce. Obchodník si její pomocí může ověřit existenci konkrétní transakce, popřípadě zkontrolovat provedení změny stavu, zaúčtování.

2.1.1.2. Změna stavu transakce

Obchodník může měnit stav transakce.

Dovolené změny stavu jsou:

• reverzal request - zrušení transakce
• process request - znovuproplacení zrušené transakce

Změna stavu transakce podléhá procesu schvalování ze strany banky. Obchodník tak přímo neprovádí aktivní operaci nad transakcí, ale pouze podává žádost o její provedení.

Žádost muže být:

• open - nová žádost - nová žádost o změnu stavu transakce
• done - provedena - daná operace je provedena, stav transakce je změněn
• postponed - odložena - operace nad danou transakcí je prověřována, o jejím provedení bude rozhodnuto později
• declined - zrušena - operace je zamítnuta, stav transakce není změněn

Doba vyřízení žádosti závisí na rychlosti vyřízení žádosti v bance. Žádost může být vyřízena, nebo zamítnuta.

Stavy požadavku na změnu stavu transakce

U transakcí ve stavu autorizováno/zaúčtováno je možné zadat částku reverzalu/znovuproplacení. Takzvaný částečný reverzal/částečné znovuproplacení. Částka musí být větší než nula a menší nebo rovna částce transakce.

Životní cyklus transakce

2.1.1.3. Reverzování transakce payment/reverse

Metoda požádá o odvolání úspěšně autorizované nebo zaúčtované transakce.

Transakce ve stavu autorizováno/nezaúčtováno bude vyřazena ze zpracování a prostředky na platební kartě plátce se uvolní, nebo nebudou strženy.

U transakce ve stavu autorizováno/nezaúčtováno lze provádět:

• plný reverzal - reverzal na celou částku transakce - částka není zadána

Transakce ve stavu autorizováno/zaúčtováno zůstane beze změny. Ale vznikne nová transakce typu reverzal, která po projití standardního životního cyklu transakce vrátí prostředky na platební kartu plátce.

U transakce ve stavu autorizováno/zaúčtováno lze provádět:

• plný reverzal - reverzal na celou částku transakce - částka není zadána
• částečný reverzal - reverzal na částku větší než nula a menší nebo rovnu částce transakce - částka je zadána

2.1.1.4. Znovuproplacení transakce payment/process

Metoda požádá o znovuproplacení reverzované transakce.

Transakce ve stavu reverzovaná, která byla reverzována ze stavu autorizováno/nezaúčtováno bude znovu zařazena ke zpracování. Její životní cyklus bude pokračovat dále a po jejím zaúčtování budou strženy prostředky z platební karty plátce.

U transakce ve stavu reverzovaná, která byla reverzována ze stavu autorizováno/nezaúčtováno lze provádět:

• plné znovuproplacení - znovuproplacení na celou částku transakce - částka není zadána

Transakce ve stavu reverzovaná, která byla reverzována ze stavu autorizováno/zaúčtováno zůstane beze změny. Ale vznikne nová transakce, která po projití standardního životního cyklu transakce strhne prostředky z platební karty plátce.

U transakce ve stavu reverzovaná, která byla reverzována ze stavu autorizováno/zaúčtováno lze provádět:

• plné znovuproplacení - znovuproplacení na celou částku transakce - částka není zadána
• částečné znovuproplacení - znovuproplacení na částku větší než nula a menší nebo rovnu částce transakce - částka je zadána

2.2. Výpisy

2.2.1. Dotazy na generované výpisy

pmAPI umožňuje obchodníkovi automatizovat stahování výpisů z POSMerchantu. Pro tuto operaci potřebuje znát, jaké výpisy mu byly vygenerovány, a následně mít možnost je stáhnout.

Výpisy nejsou shodné u všech obchodníků a ne každý obchodník využívá možnosti generování výpisů.

Výpisy mohou být generovány v časových intervalech:

• denní
• týdenní
• měsíční
• speciální

Výpisy mohou být uloženy ve formátech:

• zip - souborový formát pro kompresi a archivaci dat
• txt - souborový formát pro ukládání textových informací
• pdf - Portable Document Format – Přenosný formát dokumentů je souborový formát vyvinutý firmou Adobe pro ukládání dokumentů nezávisle na softwaru i hardwaru, na kterém byly pořízeny.
• xls - souborový formát programu Microsoft Excel vyvinutý firmou Microsoft

2.2.1.1. Seznam vygenerovaných výpisů report/list

Metoda vrátí seznam názvů souborů všech výpisů, vygenerovaných od daného data. Datum může být maximálně 1 měsíc zpět. Partnerský systém si musí pamatovat datum poslední kontroly výpisů a toto datum zaslat v následující kontrole. Pokud datum nebude uvedeno, vrátí se seznam výpisů za poslední měsíc.

2.2.1.2. Stažení konkrétního výpisu report/get

Metoda vrátí soubor požadovaného výpisu. Výpisy je možné stahovat pouze jednotlivě. Výpisy jsou nezávisle na uloženém formátu poskytovány vždy v komprimované podobě - zip.

2.3. Uživatelské reporty

2.3.1. Dotazy na generované výpisy

pmAPI obchodníkovi umožňuje automatizovat stahování transakčních exportů, jestliže nechce čekat na vygenerování přímo na portále POS Merchant. Obchodník si zvolí transakční filtr na webovém portále POS Merchant a tento filtr se aplikuje pro tvorbu uživatelského reportu. Tento report je vzápětí odeslán na email, který obchodník zadal na webovém portále.

Výpisy mohou být uloženy ve formátech:

• csv - souborový formát pro ukládání textových informací
• xls - souborový formát programu Microsoft Excel vyvinutý firmou Microsoft

2.3.1.1. Seznam vygenerovaných výpisů customReport/list

Metoda vrátí seznam názvů souborů všech výpisů, vygenerovaných od daného data. Partnerský systém si musí pamatovat datum poslední kontroly výpisů a toto datum zaslat v následující kontrole. Pokud datum nebude uvedeno, vrátí se seznam výpisů za poslední měsíc.

2.3.1.2. Stažení konkrétního výpisu customReport/get

Metoda vrátí soubor požadovaného výpisu. Výpisy je možné stahovat pouze jednotlivě.

2.4. Account Transport

2.4.1. Dotazy na zúčtovací modul

Account transport je zúčtovací modul pro odbavení bankovních karet ve veřejné dopravě. Poskytuje funkce pro agregaci jízdného, zúčtování a správu blacklistu. Account modul se stará především o agregaci plateb za jednotlivé jízdné jednou platební kartou do celkové sumy. Každé použití platební karty ve vozidle se nazývá tap. Sloučení plateb do jedné celkové sumy se nazývá vyúčtovací transakce neboli clearingová transakce. pmAPI umožňuje obchodníkovi číst seznamy tapů a clearingových transakcí ze zúčtovacího modulu.

2.4.1.1. Seznam tapů transport/tap/list

Metoda vrátí seznam jednotlivých tapů za zvolené období. Datum může být maximálně 1 měsíc zpět. Tapy lze filtrovat podle různých kritérií, která jsou popsána v ukázkách v kapitole "4.3.3.1. Seznam tapů transport/tap/list".

2.4.1.2. Seznam clearingových transakcí transport/clear/list

Metoda vrátí seznam jednotlivých clearingových transakcí za zvolené období. Datum může být maximálně 1 měsíc zpět. Transakce lze filtrovat podle různých kritérií, která jsou popsána v ukázkách níže.

2.5. DCC

2.5.1. Kurzovní lístek

pmAPI umožňuje obchodníkovi stažení aktuálního kurzovního lístku DCC, pokud má tuto službu povolenou.

Data kurzovního lístku mohou mít různé formáty:

• txt formát
• xml formát

2.5.1.1. Stažení aktuálního kurzovního lístku dcc/kurz

Metoda stáhne obchodníkovi aktuální kurzovní lístek z DCC enginu. Výstupní data kurzovního lístku budou konvertovány do formátu zadaného obchodníkem.

2.6. Pomocné funkce

2.6.1. Kontrola dostupnosti echo

Metoda pouze ověří vzájemnou funkčnost a korektnost podpisů obou stran. V odpovědi vrací čas serveru internetového portálu.