Průběh platby

Založení platby – volitelné

Krok založení platby je volitelný, je však vhodné ho implementovat v případě, kdy požadujete jistotu zabezpečeného založení platby. Vynechání implementace tohoto kroku je možné v případě, kdy jednotlivé platby nepotřebujete v systému identifikovat, ale stačí vám informace, že vám někdo zaplatil určitou částku. Je to vhodné například při implementaci dárcovských příspěvků nebo dobíjení prostředků na virtuální účet zákazníka, kdy vás zajímá jen, kdo dobíjel a jakou částku, ale nepotřebujete rozlišovat jednotlivá dobití zákazníka nebo dobití omezovat na minimální částku atd. Postup je detailně popsán v odstavci Jednoduchá integrace - bez založení platby.

Pro klasický e-shop, kde nakupující platí za konkrétní zboží, je krok založení platby důležitý, jeho vynechání nedoporučujeme.

Platbu e-shop zakládá HTTP požadavkem na server platební brány. Parametry platby, včetně unikátního referenčního čísla platby, jsou předány jako POST parametry HTTP protokolu. Tato komunikace probíhá mezi serverem Klienta a serverem platební brány. Plátce ji nevidí a nemůže měnit parametry platby. Server platební brány vrátí Klientovi unikátní identifikátor transaction ID (identifikátor v Comgate platebním systému) a URL adresu, na kterou má přesměrovat Plátce.

Příklad založení platby na pozadí – HTTP request pomocí cURL

curl -X POST -i --data "merchant=123456&price=10000&curr=CZK&label=Beatles%20-0%Help&refId=2010102600&method=ALL&prepareOnly=true&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y" https://payments.comgate.cz/v1.0/create

Příklad založení platby na pozadí – HTTP response:

HTTP/2 200 OK
content-type: application/x-www-form-urlencoded; charset=UTF-8
code=0&message=OK&transId=AB12-CD34-EF56&redirect=https%3A%2F%2Fpayments.comgate.cz%2Fclient%2Finstructions%2Findex%3Fid%3DAB12-CD34-EF56

Komunikace mezi systémem Klienta a platební bránou je zabezpečena pomocí hesla a IP whitelistu (přístup je povolen pouze z IP adres systému Klienta). Nezbytné je použití protokolu HTTPS, který znemožňuje prozrazení hesla při případném odposlouchávání komunikace. Heslo je předáváno jako POST parametr (nikoliv GET parametr) proto, aby se neukládalo v logu komunikace webového serveru.

Přesměrování na platební bránu

Po založení platby na pozadí obdrží e-shop platební URL pro zobrazení platební brány. Platební brána může být zobrazena dvěma způsoby. První způsobem je přesměrování plátce na adresu, kterou obdržel e-shop v HTTP odpovědi. Přesměrování se obvykle provádí odesláním HTTP odpovědi 302:

HTTP odpověď 302

HTTP/2 302 Found
Location: https://payments.comgate.cz/client/instructions/index?id=AB12-CD34-EF56

Druhou možností je zobrazení platební brány přímo na stránce e-shopu pomocí iframu. Pro tuto variantu je potřeba vygenerovat platební URL standardním způsobem, ale místo přesměrování zákazníka na bránu se zobrazí na stránce e-shopu iframe s platební URL.

Jednoduchá integrace – bez založení platby

Platební brána umožňuje vynechání prvního kroku založení platby na pozadí. V tomto případě je Plátce přesměrován na platební bránu bez předchozího založení platby. Přesměrování může proběhnout buď z odesláním formuláře metodou POST nebo přímým linkem pomocí metody GET. Doporučujeme způsob s použitím formuláře.

Příklad jednoduché integrace – odeslání formuláře (POST)

<form method="POST" action="https://payments.comgate.cz/v1.0/create">

    <input type="hidden" name="merchant" value="XXXX" /> <!-- identifikátor e-shopu v systému Comgate -->

    <input type="hidden" name="price" value="100" /> <!-- 100 = 1,00 Kč -->

    <input type="hidden" name="curr" value="CZK" />

    <input type="hidden" name="label" value="Moje služba" />

    <input type="hidden" name="refId" value="123456" />

    <input type="hidden" name="method" value="ALL" />

    <input type="hidden" name="country" value="CZ" />

    <button type="submit">Zakoupit</button>

</form>

Příklad jednoduché integrace - přesměrování pomocí linku (GET)

<a href="https://payments.comgate.cz/v1.0/create?merchant=XXXX&price=100&curr=CZK&label=Moje%20slu%C5%BEba&refId=10980891&method=ALL&country=CZ" rel="nofollow">Zaplatit</a>

V parametrech hypertextového odkazu zachovejte parametr rel="nofollow".

Plátce je přesměrován na webové stránky Klienta a identifikátory platby jsou předány jako GET parametry HTTP protokolu. Odeslání zboží nebo služby Plátci musí být vázáno na předání výsledku platby na pozadí, nikoliv na výsledné přesměrování Plátce na webové stránky Klienta, protože informace předané přesměrováním může Plátce snadno podvrhnout.

Předání výsledku platby na pozadí

Implementace této části vám zajistí automatické předání informace o stavu každé platební transakce přímo na váš server v okamžiku, kdy je stav platby známý. Předávání výsledku platby na pozadí je povinné. Jeho implementace a parametry jsou popsáné v sekci Push notifikace.

Výsledek platby je Klientovi předán HTTP požadavkem ze serveru platební brány na server Klienta. Identifikátory a výsledek platby jsou předány jako POST parametry HTTP protokolu. Tato komunikace probíhá na pozadí.

Plátce je přesměrován na webové stránky Klienta a identifikátory platby jsou předány jako GET parametry HTTP protokolu. Odeslání zboží nebo služby Plátci musí být vázáno na předání výsledku platby na pozadí, nikoliv na výsledné přesměrování Plátce na webové stránky Klienta, protože informace předané přesměrováním může Plátce snadno podvrhnout.

Přesměrování Plátce na web Klienta

Plátce je na základě stavu platby přesměrován na jedno ze tří URL, které e-shop zvolil při aktivaci služby. Identifikátory platby jsou předány jako GET parametry HTTP protokolu. Systém klienta musí být schopen ošetřit dvě základní situace:

• Při přesměrování Plátce na web Klienta výsledek platby ještě není známý. Platba je ve stavu PENDING. Tato situace je naprosto běžná a e-shop ji nesmí Plátci prezentovat jako chybu. Systém čeká buď na připsání platby na bankovní účet, nebo na potvrzení od Poskytovatele platby. Konečný výsledek platby se e-shop dozví později buď předáním výsledku platby na pozadí, nebo emailem, nebo v klientském portálu.
• Pokud se platební brána dozví výsledek platby okamžitě po provedení platby Plátcem, pak je Plátce směrován na příslušné URL (PAID nebo CANCELLED). Jestliže eshop implementoval předávání výsledku platby na pozadí, pak se přesměrování na web Klienta provede až po úspěšném předání výsledku platby na pozadí. Plátci nelze odeslat zboží nebo službu, kterou objednal, pouze na základě URL použité pro přesměrování, protože Plátce by mohl výsledek platby podvrhnout změnou URL ve webovém prohlížeči.

Příklad přesměrování Plátce na web Klienta – HTTP request

GET /result_ok.php?refId=2010102600&transId=AB12-EF34-IJ56 HTTP/2
Host: eshop.com