Priebeh platby
Založenie platby – voliteľné
Krok založenia platby je voliteľný, je však vhodné ho implementovať v prípade, keď požadujete istotu zabezpečeného založenia platby. Vynechanie implementácie tohto kroku je možné v prípade, kedy jednotlivé platby nepotrebujete v systéme identifikovať, ale stačí vám informácia, že vám niekto zaplatil určitú čiastku.
Je to vhodné napríklad pri implementácii darcovských príspevkov alebo dobíjaní prostriedkov na virtuálny účet zákazníka, kedy vás zaujíma len to, kto dobíja a akú sumu, ale nepotrebujete rozlišovať jednotlivé dobitie zákazníka alebo obmedziť dobitie na minimálnu čiastku atď. Pre klasický e-shop, kde platíte za konkrétny tovar, je však vynechanie tohto kroku nevhodné.
Platbu e-shopu zakladá HTTP požiadavkou na server platobnej brány. Parametre platby, vrátane unikátneho referenčného čísla platby, sú odovzdané ako POST parametre HTTP protokolu. Táto komunikácia prebieha medzi serverom Klienta a serverom platobnej brány. Platiteľ ju nevidí a nemôže meniť parametre platby. Server platobnej brány vráti Klientovi unikátny identifikátor transaction ID (identifikátor v Comgate platobnom systéme) a URL adresu, na ktorú má presmerovať Platiteľ.
Parametre volania
| parameter | typ | povinný | popis |
|---|---|---|---|
| merchant | string | A | identifikátor e-shopu v systéme Comgate |
| test | boolean | A | Hodnota „true“ znamená, že platba bola založená ako testovacia, hodnota „false“ znamená produkčnú verziu. |
| price | integer | A | cena za výrobok v centoch alebo halieroch |
| curr | string | A | kód meny podľa ISO 4217 |
| label | string | A | krátky opis produktu (1 – 16 znakov) |
| refId | string | A | referencia platby (variabilný symbol, číslo objednávky) v systéme e-shopu |
| payerId | string | N | identifikátor Platiteľa v systéme e-shopu |
| payerName | string | N | odovzdanie mena účtu patriaceho Platiteľovi |
| payerAcc | string | N | odovzdanie čísla účtu Platiteľa |
| method | string | N | použitá metóda platby, z tabuľky platobných metód |
| account | string | N | identifikátor bankového účtu e-shopu, na ktorý Comgate Payments prevedie peniaze |
| string | A | kontaktný email na Platiteľa | |
| phone | string | N | kontaktný telefón na Platiteľa |
| name | string | N | identifikátor produktu - podľa tejto položky je možné vyhľadávať v štatistikách platieb Comgate platobného systému. |
| transId | string | A | unikátny alfanumerický identifikátor (kód) transakcie (transactionId) |
| secret | string | A | heslo pre komunikáciu na pozadí |
| status | string | A | status - aktuálny stav transakcie, hodnoty PAID - platba bola úspešne zaplatená CANCELLED - platba nebola dokončená korektne a je zrušená Authorized - vyžiadaná predautorizácia prebehla úspešne |
| fee | string | N | Ak má e-shop nastavené automatické strhávanie poplatku za platbu, bude v tomto poli spočítaný poplatok za transakciu, inak bude pole nadobúdať hodnoty "unknown". |
Parametre odpovedí
| parameter | typ | povinný | popis |
|---|---|---|---|
| code | integer | A | Návratový kód metódy a opis chyby: systém očakáva HTTP kód 200 v prípade, že výsledok platby bol v poriadku prijatý. |
Príklad založenia platby na pozadí - HTTP request:
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
Príklad založenia 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
Komunikácia medzi systémom Klienta a platobnou bránou je zabezpečená pomocou hesla a IP whitelistu (prístup je povolený len z IP adries systému Klienta). Nevyhnutné je použitie protokolu HTTPS, ktorý znemožňuje prezradenie hesla pri prípadnom odpočúvaní komunikácie. Heslo je odovzdávané ako POST parameter (nie GET parameter) preto, aby sa neukladalo v logu komunikácie webového servera.
Presmerovanie na platobnú bránu
Po založení platby na pozadí dostane e-shop platobné URL na zobrazenie platobnej brány. Platobná brána môže byť zobrazená dvoma spôsobmi. Prvým spôsobom je presmerovanie platiteľa na adresu, ktorú dostal e-shop v HTTP odpovedi. Presmerovanie sa zvyčajne vykonáva odoslaním HTTP odpovede 302:
HTTP odpoveď 302
HTTP/2 302 Found
Location: https://payments.comgate.cz/client/instructions/index?id=AB12-CD34-EF56
Druhou možnosťou je zobrazenie platobnej brány priamo na stránke e-shopu pomocou iframe. Pre tento variant je potrebné vygenerovať platobné URL štandardným spôsobom, ale namiesto presmerovania zákazníka na bránu sa zobrazí na stránke e-shopu iframe s platobnou URL.
V prípade vynechania prvého kroku založenia platby na pozadí je platba založená až pri presmerovaní Platiteľa z webu Klienta na server platobnej brány alebo odoslaní webového formulára z webu Klienta na server platobnej brány. Parametre platby, vrátane unikátneho referenčného čísla platby, sú odovzdané ako GET alebo POST parametre HTTP protokolu.
Príklad založenia platby presmerovaním (odoslaním webového formulára) - HTTP request
curl -X POST -i --data "merchant=123456&price=10000&curr=CZK&label=Beatles%20-20Help&refId=2010102600&method=ALL" https://payments.comgate.cz/v1.0/create
Odovzdanie výsledku platby na pozadí
Implementácia tejto časti vám zaistí automatické odovzdanie informácie o stave každej platobnej transakcie priamo na váš server v okamihu, keď je stav platby známy. Odovzdávanie výsledku platby na pozadí je povinné.
Výsledok platby je Klientovi odovzdaný HTTP požiadavkou zo servera platobnej brány na server Klienta. Identifikátory a výsledok platby sú odovzdané ako POST parametre HTTP protokolu. Táto komunikácia sa uskutočňuje na pozadí.
Platiteľ je presmerovaný na webové stránky Klienta a identifikátory platby sú odovzdané ako GET parametre HTTP protokolu. Odoslanie tovaru alebo služby Platiteľa musí byť viazané na odovzdanie výsledku platby na pozadí, nie na výsledné presmerovanie Platiteľa na webové stránky Klienta, pretože informácie zaslané presmerovaním môže Platiteľ ľahko podstrčiť.
Príklad odovzdania výsledku platby na pozadí - HTTP request
curl -X POST -i --data "merchant=merchant_com&test=false&price=10000&curr=CZK&label=Beatles%20-%20Help&refId=2010102600&method=CARD&email=info%40customer.com&phone=%2B420123456789&transId=AB12-EF34-IJ56&secret=ZXhhbXBsZS5jb206QUJDeHl6&status=PAID" https://example.com/handler.php
Príklad odovzdania výsledku platby na pozadí - HTTP response
HTTP/2 200 OK
content-type: application/x-www-form-urlencoded; charset=UTF-8
Komunikácia medzi systémom Klienta a serverom platobnej brány je zabezpečená pomocou hesla a IP whitelistu. Prístup musí byť povolený iba z IP adresy servera platobnej brány. Rozsahy IP adries sú definované v sekcii Zabezpečenie. Je povinné použiť protokol HTTPS, ktorý znemožňuje prezradenia hesla pri prípadnom odpočúvaní komunikácie. Heslo je odovzdávané ako POST parameter (nie GET parameter) preto, aby sa neukladalo v logu komunikácie webového servera.
E-shop na svojej strane zabezpečí, že tovar (služba) poskytnutý v rámci zaplatenej transakcie (identifikovanej pomocou unikátneho transaction ID) bude vydaný Platiteľom iba raz (aj pri opakovanom odovzdaní výsledku rovnakej platby na server Klienta).
Presmerovanie Platiteľa na web Klienta
Platiteľ je na základe stavu platby presmerovaný na jedno z troch URL, ktoré e-shop zvolil pri aktivácii služby. Identifikátory platby sú odovzdané ako GET parametre HTTP protokolu. Systém klienta musí byť schopný ošetriť dve základné situácie:
- Pri presmerovaní platiteľa na web klienta výsledok platby ešte nie je známy. Platba je v stave PENDING. Táto situácia je úplne bežná a e-shop ju nesmie platiteľovi prezentovať ako chybu. Systém čaká buď na pripísanie platby na bankový účet alebo na potvrdenie od poskytovateľa platby. Konečný výsledok platby sa e-shop dozvie neskôr buď odovzdaním výsledku platby na pozadí alebo e-mailom alebo na klientskom portáli.
- Ak sa platobná brána dozvie výsledok platby okamžite po uskutočnení platby platiteľom, potom je platiteľ smerovaný na príslušné URL (PAID alebo CANCELLED). Ak e-shop implementoval odovzdávanie výsledku platby na pozadí, potom sa presmerovanie na web Klienta vykoná až po úspešnom odovzdaní výsledku platby na pozadí. Platiteľovi nemožno odoslať tovar alebo službu, ktorú objednal, iba na základe URL použitej na presmerovanie, pretože platiteľ by mohol výsledok platby podstrčiť zmenou URL vo webovom prehliadači.
Príklad presmerovania Platiteľa na web Klienta - HTTP request
GET /result_ok.php?refId=2010102600&transId=AB12-EF34-IJ56 HTTP/2
Host: eshop.com