Průběh platby - csob/platebnibrana GitHub Wiki
Z pohledu plátce e-shopu se platba odehrává standardním způsobem, na který je plátce zvyklý u obdobných řešení využívaných bankami v České republice. Po dokončení nákupu proběhne z e-shopu přesměrování na platební bránu, kde plátce vyplní údaje karty a potvrdí platbu. Následně proběhne ověření platby a autorizace platby. Plátce je informován o výsledku platby a přesměrován zpět do e-shopu.
img/cs_CZ/payment-process-highlevel-cz.png
Pod pokličkou se ovšem odehrává mnohem více událostí, které plátce nevidí. Jednotlivé operace odehrávající se na pozadí zachycuje následující obrázek. Dále projdeme jednotlivé kroky platebního procesu, popíšeme si data předávaná mezi jednotlivými systémy a probereme události odehrávající se uvnitř.
img/cs_CZ/payment-process-detail-cz.png
Diagram ukazuje provedení platby ze strany plátce a předpokládá, že dojde k úspěšnému obchodu a odeslání zboží e-shopem. Pokud dojde ke komplikacím, změnám či zrušení objednávky ze strany plátce či obchodníka, je v dalším procesu k dispozici rozhraní umožňující správu platby a její dodatečně zrušení. To si ale probereme až v dále popsané sekci správa stavu transakce.
Životní cyklus transakce
Transakce platby prochází několika kroky, které ovlivňuje obchodník, plátce a stav platební karty. Celý životní cyklus od založení platby po její dokončení a možné následné stavy na popud obchodníka ukazuje diagram níže, popíšeme si je detailně:
img/cs_CZ/state-transitions-cz.png
1) Platba založena je úvodní stav po volání metody payment/init. Po úspěšném založení se vyčkává na přesměrování plátce z e-shopu na stránku platební brány. Pokud založení transakce nelze provést, například z důvodu chyby ve vstupních datech nebo nepovolené operace daného obchodníka, požadavek přejde do do stavu 6) Platba zamítnuta.
2) Platba probíhá po přesměrování plátce na stránku platební brány. Na pozadí probíhající platby se odehrává mnoho kroků provedení platby kartou. Tyto kroky jsou pro obchodníka skryty za průběhem platby, zajímá ho až samotný výsledek. Ten může být:
- 3) Platba zrušena - platba byla zrušena plátcem na platební bráně;
- 6) Platba zamítnuta - zamítnuto bankou z důvodu nedostatku prostředků, nepotvrzení 3D ověření plátcem či z jiného důvodu a nebo byl proces přerušen, např. protože plátce zavřel prohlížeč;
- 4) Platba potvrzena - platba byla provedena a čeká, až ji obchodník zařadí do zúčtování. Do tohoto stavu se úspěšná platba dostane, pokud je automatické zařazení do zúčtování vypnuto;
- 7) Čekání na zúčtování - platba byla provedena a automaticky zařazena do zúčtování.
3) Platba zrušena: Tento stav nastane, pokud plátce na stránce platební brány klikne na tlačítko zrušit. Plátce se vrací automaticky do e-shopu (platební brána jej přesměruje) a z pohledu životního cyklu transakce je tento stav koncový. Chce-li plátce znovu tu samou objednávku v e-shopu zaplatit kartou, e-shop musí vygenerovat zcela nový platební požadavek.
4) Platba potvrzena: Tento stav nastane po úspěšném provedení transakce v případě, že je automatické zařazení do zúčtování vypnuto. Již v založení platby říkáme, zda chceme transakci ihned po potvrzení automaticky poslat do zúčtování a převést tak peníze na účet obchodníka, nebo zda necháme autorizovanou transakci čekat, např. až připravíme zboží, a teprve po odeslání zboží pošleme transakci do zúčtování.
V tomto stavu je možné ponechat platbu maximálně po dobu sedmi dnů, kdy je platba ze strany banky garantována a na kartě plátce jsou prostředky blokovány. POZOR! Po uplynutí této doby již není možné transakci zařadit do zúčtování! (platba je odvolána, prostředky na kartě plátce jsou systémem automaticky odblokovány a banka platbu již negarantuje).
5) Platba odvolána: Dokud neprojde potvrzená platba zúčtováním, lze ji odvolat. To znamená, že nebude vůbec držiteli karty účtována, blokované prostředky na kartě se uvolní a neplatí se žádný poplatek. Tento stav je koncový a nelze jej vrátit. Počet odvolaných plateb obchodníkem je bankou monitorován.
Spoléhat na možnost odvolání platby lze pouze u transakcí, které dosud nebyly zúčtovány. Odvolat platbu lze u transakcí ve stavu „Platba potvrzena“ (4) pouze do té doby, dokud nebude zařazena do zúčtování a neproběhne samotné zúčtování. U transakcí ve stavu „Čekání na zúčtování“ (7) lze odvolat platbu maximálně do půlnoci daného dne, po této době se provádí zúčtování transakcí, u zúčtované platby lze již jen provést operaci vrácení prostředků.
6) Platba zamítnuta: Tento stav byl již popsán výše, důvodů zamítnutí platby je více a jsou detailně rozlišeny v návratovém kódu operace. Principiálně je lze řadit do několika skupin:
- inicializace platby obsahovala chybná data
- obchodník nemá povolenou platební operaci
- plátce neprovedl správně ověření (3D Secure)
- banka plátce (vydavatel karty) nepovolila platbu kartou
- plátce zavřel prohlížeč a transakce vypršela
Specifickým stavem je zamítnutí platby ze strany banky. Teprve návratový kód upřesňuje, z jakého důvodu banka vydavatele karty transakci zamítla. Z pohledu obchodníka jde však o neúspěšnou platbu a tento detail je pouze informativní.
Platební brána v případě neúspěchu platby kartou plátce ihned neodsoudí k neúspěchu, ale sama mu znovu nabídne možnost platit jinou kartou. Tím se sníží skupina plátců, které neúspěch a návrat do e-shopu odradí. Z pohledu obchodníka je takováto "transakce napodruhé" po celou dobu ve stavu Platba probíhá a až výsledný úspěch či neúspěch ji přesune do příslušného stavu.
7) Čekání na zúčtování je stav, kdy jsou transakce již řazeny do fronty a dle nastavení zúčtovacích pravidel banky jsou zpracovávány. Dokud transakce není zúčtována, lze ji stále odvolat. Tento postup již byl popsán výše.
8) Platba zúčtována je pro obchodníka ten správný koncový stav. Vše proběhlo, transakce byla zařazena do zúčtování, zúčtování bylo provedeno a peníze jsou na cestě. Tento stav je sice koncový, nicméně pokud se obchodník rozhodne transakci zrušit (např. pokud zákazník objednávku zruší nebo zboží vrátí v zákonné lhůtě), může prostředky vrátit zákazníkovi pomocí operace vrácení prostředků. POZOR! Při platbě platebním tlačítkem ČSOB se autorizovaná transakce dostane ze stavu 2 přímo do stavu 8. Je proto nutné, aby e-shop vyhodnocoval i stav 8 jako zaplaceno.
9) Zpracování vrácení: Pokud obchodník přesto zažádá o vrácení prostředků, přesune se existující transakce do tohoto stavu a operace probíhá. Zpracování vrácení je v bance schvalováno na základě podkladů dodaných obchodníkem bance, proto může tento stav trvat i několik dní.
10) Platba vrácena: Sem se dostává životní cyklus transakce po schválení jejího vrácení a reálném provedení transakce opačným směrem k původnímu plátci.
Jednotlivé kroky platebního procesu
Založení platby: payment/init
V okamžiku, kdy je na e-shopu iniciována koncová fáze nákupu, přechází se k platbě a je vybrána metoda platby kartou, e-shop zakládá platbu na platební bráně. Kromě standardních údajů, jako je vlastní identifikace obchodníka, částka a referenční číslo objednávky, může e-shop zaslat do platební brány také detail nákupu včetně jedné, nebo dvou položek košíku dle payment/init specifikace. Tím se výrazně zpřehlední platební proces a zvýší důvěra zákazníka v korektní průběh operací na e-shopu a platební bráně.
Referenční číslo objednávky přiděluje e-shop obchodníka. Ve výsledku se referenční číslo objednávky objeví na výpisu transakcí z banky. Použije se tedy v systému obchodníka (účetnictví) pro párování plateb e-shopu proti bankovnímu účtu, a musí tedy splňovat podmínku variabilního symbolu - numerickou hodnotu o maximálně deseti místech. V aplikaci ČSOB POS Merchant je referenční číslo objednávky zobrazeno ve sloupci Variabilní symbol.
Po založení platby přiřadí platební brána každé transakci jednoznačné ID platby payID. Tento identifikátor se vrací v odpovědi na payment/init a nese se celou platební transakcí ve všech stavech.
Číslo objednávky, které obchodník předává platební bráně při založení platby, musí být v rámci jeho e-shopu unikátní. V případě, že obchodník založí na platební bráně dvě transakce se stejným číslem objednávky, mají tyto transakce sice odlišné
payID, ale na výpisu z banky se objeví jako dvě platby se stejným variabilním symbolem.
Pokud je zákazník na e-shopu přihlášen a jeho identita je známá, je možné předat také jednoznačný identifikátor zákazníka. To umožní, aby si zákazník na bráně svou platební kartu bezpečně uložil a při následných návštěvách tohoto e-shopu ji mohl znovu použít bez opisování dlouhého čísla karty.
Přesměrování na bránu: payment/process
Pokud je platba na bráně úspěšně založena, může v následných krocích e-shop přesměrovat plátce na bránu. V odkazu předává pouze svůj jednoznačný identifikátor této platby, všechna ostatní data platební operace stejně jako obsah košíku a identita obchodníka jsou již na bráně připraveny během kroku Založení platby.
Operaci přesměrování na bránu je potřeba použít v případě, že zákazník opakovaně přechází tam a zpět mezi e-shopem a platební bránou (např. pomocí navigace v prohlížeči). Pro jednou založenou platbu s již nastaveným číslem objednávky, kdy tato platba má na platební bráně přidělené unikátní
payID, nelze znovu založit transakci se stejným číslem objednávky.
Potřebujete-li používat jako číslo objednávky opakovaně např. klientské číslo vašeho zákazníka, kontaktujte prosím podporu, kontrolu duplicitních čísel objednávek pro vás rádi vypneme.
Zjištění stavu platby: payment/status
Systém e-shopu může kdykoli zjistit stav kterékoli své platby na platební bráně. Zavoláním této metody dostává zpět informaci, zda platba probíhá, případně ve kterém kroku se nachází, a po dokončení platby pak dostává informaci o tom, s jakým výsledkem byla platba dokončena.
Toto volání je nepovinné, u jednodušších implementací e-shopu nemusí být použito a čeká se pouze na návrat plátce zpět jeho přesměrováním na návratovou URL e-shopu.
Správa stavu transakce, vratky
E-shop může ověřit stav transakce v jejím průběhu, nebo po jejím dokončení. Transakce je držena v aktivní části brány následujících 48 hodin po jejím provedení. Pokud plátce (například omylem) vyvolá z historie prohlížeče opět platební bránu, nedojde k žádným komplikacím. Bude mu zobrazena korektní potvrzovací stránka platební brány s informací, jak tato platba dopadla.
Jak vyplývá z výše popsaného životního cyklu transakce, po úspěšném dokončení platby je ještě několik kroků, kterými může obchodník řídit její stav.
Odvolání transakce: payment/reverse
Metoda odvolá úspěšně autorizovanou transakci a vyřadí ji ze systému, transakce nebude provedena a prostředky na kartě plátce se uvolní. Metodu lze použít pouze pro nezaúčtované transakce. Je nutno počítat s tím, že při volání metody ve stavu 7) Čekání na zúčtování může dojít ke zpracování zúčtování transakce, metoda vrátí chybu a transakce již bude proplacena.
Zařazení transakce do zúčtování: payment/close
Tuto operaci voláme pouze v případě, že v založení platby máme vypnuto její automatické zařazení do zúčtování. Volání této funkce zařadí transakci do zúčtování a může být v e-shopu například spojena s okamžikem odeslání zboží.
Žádost o vrácení transakce: payment/refund
Tuto operaci voláme v případě, že je třeba vrátit prostředky zpět plátci. Příkladem je reklamace zboží, zrušení objednávky nebo odstoupení od koupě na e-shopu v zákonné lhůtě. Od API v1.5 lze provést tzv. částečný refund, vrácená částka je tedy menší než původní autorizovaná částka.
Mikrostavy
Mikrostavy transakcí přinášejí e-shopu detailnější informace o průběhu nebo stavu zpracování transakce. Použití mikrostavů je nepovinné, jedná se o dodatečnou funkcionalitu. Pro obsluhu transakcí na platební bráně není nutné s mikrostavy pracovat, jako základ stačí pracovat se základními stavy životního cyklu transakce. Platební brána poskytuje mikrostav v odpovědích do e-shopu, které obsahují stav transakce (tj. např. v odpovědi na volání payment/status).
Použití mikrostavů
Mikrostavy lze v e-shopu využít pro získání lepšího přehledu o průběhu nebo stavu transakce. Business hodnota významu mikrostavu se odvíjí od hlavního stavu, ve kterém se transakce nachází.
Mikrostavy ve stavu 2 (platba probíhá) jsou informací o tom, co zákazník na platební bráně dělá, resp. v jakém je kroku platebního procesu. Pro platební metody integrované přímo do e-shopu (Apple Pay, Google Pay, OneClick platba) je to pak informace o interakci zákazníka s externím poskytovatelem platební metody - tyto informace bývají ale velice omezené, nejlepší informace o průběhu platby ve stavu 2 má platební brána o platbě kartou, kterou zpracovává sama.
Mikrostavy ve stavu 3 (platba zrušena) jsou informací o způsobu zrušení platby, případně (je-li to možné) dávají e-shopu i informaci o tom, zda zákazník provedl pokus o platbu.
Mikrostavy ve stavu 6 (platba zamítnuta) jsou informací o důvodu zamítnutí, případně expirace platby.
Mikrostavy ve stavu 10 (platba vrácena) umožňují rozlišit mezi úplnou vratkou (další vratky na takovou transakci již není možné zadat) a částečnou vratkou (je možné provést další vratky až do výše původně autorizované částky).
Mikrostavy pro platební metody
Mikrostavy pro jednotlivé platební metody se liší podle průběhu platebního procesu, logiky platební metody a situací, do kterých se může zákazník dostat. Mikrostav vždy nese informaci o platební metodě, která právě probíhá nebo kterou byla transakce dokončena. Je-li to možné, mikrostavy dávají e-shopu i informaci o tom, zda zákazník provedl pokus o platbu.