Platobná brána v aplikácii

Integrácia platobnej brány do mobilnej alebo desktopovej aplikácie (ďalej len Aplikácia) je principiálne zhodná s integráciou do webového prostredia. Aj v tomto prípade sa používa štandardný API protokol.

Vo webovom prostredí je možné zvoliť buď presmerovanie na platobnú bránu, alebo zobrazenie platobnej brány v iframe. V prostredí mobilných aplikácií je postup obdobný, avšak samotná platba musí byť otvorená v komponente určenom na bezpečné zobrazovanie webového obsahu, typicky pomocou Chrome Custom Tabs pre Android alebo SFSafariViewController pre iOS, ďalej len ako „Komponenty na zobrazovanie webovej stránky“.

Použitie WebView je z hľadiska funkčnosti a bezpečnosti nevhodné.

Alternatívne je možné presmerovanie na platobnú bránu realizovať prostredníctvom Android Intent alebo pomocou Apple URL Schemes a Universal Links.

WebView

Upozornenie

Použitie technológie WebView sa dôrazne neodporúča. WebView neposkytuje plnohodnotnú funkcionalitu webového prehliadača, v dôsledku čoho platobná brána ani platobné metódy, ako sú Apple Pay a Google Pay, nebudú fungovať korektne. Toto obmedzenie sa týka najmä technológií WebView pre Android a WKWebView pre iOS.

Je potrebné používať komponenty s plnou funkcionalitou webového prehliadača, konkrétne Chrome Custom Tabs pre platformu Android a SFSafariViewController pre platformu iOS.

Zobrazenie v mobilnej aplikácii

Pre platformu Android je určená komponenta Chrome Custom Tabs, zatiaľ čo pre platformu iOS sa používa komponenta SFSafariViewController, ďalej len ako „Komponenty na zobrazovanie webovej stránky“.

Informácie

Komponenta na zobrazovanie webovej stránky by mala byť zobrazená cez čo najväčšiu časť obrazovky, aby mal platobný proces dostatok priestoru a bol maximalizovaný používateľský komfort.

Priebeh spracovania platby

1. Aplikácia kontaktuje svoj Server a vytvorí objednávku.
2. Server vykoná HTTP request na Comgate API (/create) a založí platbu. Odpoveď Comgate API obsahuje informácie o založenej platbe.
3. Server si prijaté údaje uloží a odovzdá ich Aplikácii (ukážky parsovania query stringu v PHP, JavaScripte, Kotlinu, Jave a Swifte).
4. Aplikácia vytvorí cez čo najväčšiu časť displeja Komponentu na zobrazovanie webovej stránky a načíta v nej URL platobnej brány (parameter redirect).
5. Platiteľovi sa zobrazí platobná brána.
6. Počas realizácie platby sa spustí mechanizmus sledovania stavu platby (status watcher), ktorého cieľom je čo najrýchlejšia synchronizácia stavu zo Servera do Aplikácie. K dispozícii sú nasledujúce metódy:
   • Polling – krátke opakované requesty na Server (typicky každé ~3 sekundy),
   • Long polling – Server drží request otvorený do okamihu dostupnosti dát alebo do vypršania timeoutu; pri neznámom stave sa dotaz opakuje,
   • WebSocket – plne duplexný komunikačný kanál umožňujúci Serveru odosielať informácie o stave platby v reálnom čase.
7. Platiteľ vykoná úhradu objednávky.
8. Po vykonaní úhrady je Server informovaný o zmene stavu platby prostredníctvom Push notifikácie a túto informáciu uloží.
9. Server overí stav platby dotazom na Comgate API (/status):
   • ak platba nie je potvrdená ako uhradená, dotaz sa opakuje približne každé 3 sekundy; po približne 10 pokusoch (cca 30 sekúnd) je vhodné dotazovanie ukončiť a pokračovať na pozadí s intervalom približne 30 minút,
     Venujte zvýšenú pozornosť

     V niektorých prípadoch môže spracovanie platby trvať až do 12:00 nasledujúceho pracovného dňa.

   • ďalší postup opakovania dotazov sa riadi podľa stavov platieb.
10. Platobná brána zobrazená v Komponente na zobrazovanie webovej stránky deteguje úspešnú úhradu:
11. tesne pred presmerovaním odošle post message, ktorú je možné zachytiť a na jej základe Komponentu na zobrazovanie webovej stránky skryť,
12. prípadne dôjde k presmerovaniu platiteľa na URL definovanú v nastavení prepojenia obchodu; na túto URL by mala Aplikácia reagovať a Komponentu na zobrazovanie webovej stránky skryť.
13. Aplikácia kontaktuje svoj Server a overí finálny stav platby.
14. Aplikácia sprístupní platiteľovi zaplatenú službu.

Sekvenčný diagram

Ako rozpoznať okamih na skrytie Komponenty na zobrazovanie webovej stránky

Ako bolo uvedené v bode 10, existujú dva základné mechanizmy, pomocou ktorých je možné rozpoznať, že platba bola dokončená a Komponentu na zobrazovanie webovej stránky je možné skryť:

1. zachytenie odoslanej post message,
2. presmerovanie platiteľa na URL definovanú v nastavení prepojenia obchodu.

Post message

Bezprostredne pred presmerovaním platiteľa mimo platobnej brány je odosielaná post message obsahujúca informáciu o stave platby. Túto správu je možné zachytiť a na jej základe iniciovať skrytie Komponenty na zobrazovanie webovej stránky.

Štruktúra post message:

{
   "value":{
      "id": "XXXX-XXXX-XXXX",
      "status": "PAID", // PAID, CANCELLED, AUTHORIZED, PENDING
      "refId": "hodnota-refId"
   },
   "scope": "comgate-to-eshop",
   "action": "status"
}

Pri spracovaní post message musí byť vždy overené, že hodnota scope zodpovedá "comgate-to-eshop" a hodnota action je "status". Ostatné post messages musia byť ignorované.

Zároveň je potrebné zdôrazniť, že stav platby získaný prostredníctvom post message sa nepovažuje za dôveryhodný. Skutočný stav platby musí byť vždy overený dotazom na Comgate API.

Presmerovanie platiteľa

Alternatívne môže byť platiteľ po dokončení platobného procesu presmerovaný na URL vlastného Servera. V tomto prípade musí Aplikácia automaticky detegovať toto presmerovanie a na jeho základe skryť Komponentu na zobrazovanie webovej stránky.

Presmerovacie URL je možné nastaviť v klientskom portáli alebo ich definovať pri zakladaní platby prostredníctvom API:

• URL zaplatený (url_paid) – pre úspešne zaplatené platby (PAID, AUTHORIZED),
• URL zrušený (url_cancelled) – pre zrušené alebo expirované platby (CANCELLED),
• URL nevybavený (url_pending) – pre prebiehajúce platby (PENDING),
• URL na odovzdanie výsledku platby – nastavuje sa výhradne v klientskom portáli v rámci prepojenia obchodu.

Android Intent

Comgate tiež umožňuje integráciu návratov z platobnej brány pomocou Intent. Výhodou tohto riešenia je, že nie je potrebné implementovať Komponentu na zobrazovanie webovej stránky a na zobrazenie platby sa použije predvolený prehliadač, ktorý následne vráti aplikácii focus.

Priebeh spracovania platby

1. Aplikácia kontaktuje svoj Server a vytvorí objednávku.
2. Server vykoná HTTP request na Comgate API (/create), čím založí platbu. Comgate API vráti odpoveď obsahujúcu informácie o platbe.
3. Server si informácie získané z Comgate API uloží a odovzdá ich aj Aplikácii (ako parsovať query string v PHP, JavaScripte, Kotline, Jave a Swifte).
4. Aplikácia otvorí platbu v predvolenom prehliadači platiteľa (použije URL na platobnú bránu z parametra "redirect"). Tým aplikácia stratí focus.
5. Platiteľovi sa načíta platobná brána v predvolenom prehliadači.
6. Platiteľ zaplatí objednávku.
7. Po tom, čo platiteľ vykoná úhradu, je Server pomocou Push notifikácie informovaný o novom stave platby. Túto informáciu si uloží.
8. Server si overí stav platby tým, že sa dotáže Comgate API (/status), či je platba skutočne zaplatená.
   • Ak nie, dotazuje sa periodicky každé cca 3 sekundy znova. Po 10 dotazoch (cca 30 sekundách) je vhodné dotazovanie ukončiť a na pozadí sa dotázať Servera na stav raz za 30 minút.
     Venujte zvýšenú pozornosť

     V niektorých prípadoch môže spracovanie platby trvať až do 12:00 nasledujúceho pracovného dňa.

   • V opakovaní dotazovania je možné pokračovať podľa stavov platieb.
9. Platiteľ je následne presmerovaný späť do Aplikácie a tá získa "focus".
10. Aplikácia kontaktuje svoj Server a overí si stav platby.
11. Aplikácia sprístupní zaplatenú službu.

Sekvenčný diagram

Nastavenie návratových URI pre Intent

V súčasnosti je možné Android Intent použiť iba ako parametre pri zakladaní platby cez Comgate API (/create). Jedná sa o parametre:

• url_paid - URI pre presmerovanie platiteľa po zaplatení platby,
• url_cancelled - URI pre presmerovanie platiteľa po zrušení platby,
• url_pending - URI pre presmerovanie platiteľa, ak platba ešte nie je vybavená.

Platobná brána sa následne bude snažiť použiť tento Intent v predvolenom prehliadači a presmerovať tak platiteľa späť do vašej aplikácie.

Venujte zvýšenú pozornosť

Android Intent nie je v súčasnosti možné nastaviť v klientskom portáli.

Android Intent formát

Je možné používať prakticky ľubovoľný formát Intentu. Veľmi často sa stretávame s obecným zápisom v tvare:

• intent://host/path?transactionId=XXXX-XXXX-XXXX&status=PAID#Intent;package=com.example.package;end

Je možné sa tiež stretnúť s viac špecifickými Intentami napr.:

• myapp://payment/success?transactionId=XXXX-XXXX-XXXX&status=PAID

Informácie

V oboch prípadoch sú Intenty úzko späté s konkrétnou aplikáciou. Ich funkčnosť je potrebné implementovať v rámci samotnej aplikácie.

Apple URL Schemes a Universal Links

Apple na svojich zariadeniach poskytuje mechanizmy, ktoré umožňujú aplikáciám efektívne spracovať presmerovanie. Medzi tieto mechanizmy patria URL Schemes a Universal Links.

URL Schemes

Vlastné URL schémy umožňujú aplikáciám registrovať jedinečné odkazy, pomocou ktorých môže platobná brána presmerovať platiteľa späť do aplikácie.

myapp://payment/success?transactionId=XXXX-XXXX-XXXX&status=PAID

Universal Links

Universal Links sú štandardné HTTP/HTTPS odkazy, ktoré automaticky otvoria aplikáciu. Tento mechanizmus je preferovaný kvôli lepšej bezpečnosti a používateľskej prívetivosti.

https://example.com/payment/success?transactionId=XXXX-XXXX-XXXX&status=PAID

Návratové URL

Pri nastavovaní platieb cez Comgate API je možné definovať návratové URL, ktoré určujú, kam bude platiteľ presmerovaný v rôznych situáciách:

• url_paid: presmerovanie po úspešnej platbe (PAID, AUTHORIZED)
• url_cancelled: presmerovanie po zrušenej alebo expirovanej platbe (CANCELLED)
• url_pending: presmerovanie pre prebiehajúce platby (PENDING)

Venujte zvýšenú pozornosť

Návratové URL vo formáte Universal Links je možné definovať ako cez Comgate API, tak aj v klientskom portáli.
URL Schemes je momentálne možné nastaviť iba cez Comgate API.