Protokol API

Často kladené otázky

Kde nájdem prihlasovacie údaje do API?

Prihlasovacie údaje nájdete v klientskom portáli v sekcii „Integrácia“ > „Nastavenie obchodu“ a potom „Prepojenie obchodu“.

Čo je login a čo heslo do API?

Login je identifikátor prepojenia obchodu (vo väčšine prípadov šesťmiestne číslo) a heslo náleží k tomuto identifikátoru. Obidva tieto údaje sú uvedené v klientskom portáli v sekcii „Integrácia“ > „Nastavenie obchodu“ > „Prepojenie obchodu“.

Čo je založenie na pozadie vs. založenie presmerovaním a prečo je založenie na pozadie lepšie?

Založenie platby na pozadie slúži pre bezpečné a garantované založenie platby s parametrami, ktoré korešpondujú s e-shopovou objednávkou. Platca teda nemôže ovplyvniť napr. cenu, musí ju celú uhradiť. Oproti tomu založenie presmerovaním sa používa napr. pre dary, u niektorých môže platca ľubovoľne meniť cenu platby. Vo väčšine prípadov teda doporučujeme založenie platby na pozadie (volanie z e-shopu na API Comgate).

Prečo nie je dobré začať implementáciu v SOAP?

SOAP podporujeme z historických dôvodov a už sa nevyvíja, preto nie je dobré v ňom začať implementáciu.

Ako nastaviť IP whitelist?

API Comgate je chránený pomocou IP whitelistu. U každého e-shopu evidujeme IP adresy, z ktorých je možné komunikovať s našim API. Pridanie povolených IP adries môžete vykonať v klientskom portáli „Integrácia“ > „Nastavenie obchodu“ a potom „Prepojenie obchodu“.

Čo sa má nastaviť v PENDING, PAID a CANCELLED URL v prepojení obchodu?

Je potrebné vyplniť URL, pokiaľ používate HTTP POST alebo REST protokol (u SOAPU nie je nutné). Prvé tri URL slúžia k presmerovaniu používateľa, posledné URL slúži k odovzdaniu výsledku na pozadie. Bez správne nastaveného URL sa e-shop o výsledku transakcie nemusí dozvedieť. V prípade, že nevyplníte „pending URL“, na platobnej bráne sa nebude zobrazovať tlačidlo „Návrat do e-shopu“. PENDING, PAID a CANCELLED URL sú adresy na endpointy v e-shope, kam presmerujeme platcu z platobnej brány, pokiaľ dôjde napríklad k úspešnej úhrade platby. URL pre odovzdanie výsledku platby slúži pre komunikáciu nášho API s e-shopom (odovzdanie výsledku platby do e-shopu).

Ako nastaviť URL?

Je potrebné vyplniť URL, pokiaľ používate HTTP POST alebo REST protokol (u SOAPU nie je nutné). Prvé tri URL slúžia k presmerovaniu používateľa, posledné URL slúži k odovzdaniu výsledku na pozadie. Bez správne nastaveného URL sa e-shop o výsledku transakcie nemusí dozvedieť. V prípade, že nevyplníte „pending URL“, na platobnej bráne sa nebude zobrazovať tlačidlo „Návrat do e-shopu“.

Ako nastaviť založenie presmerovaním?

Založenie presmerovaním je potrebné najskôr povoliť v prepojení obchodu v klientskom portáli „Integrácia“ > „Nastavenie obchodov“ > „Prepojenie obchodu“. Nie je potrebné vyplňovať IP whitelist a nie je nutné posielať heslo pri zakladaní požiadavky. Tento typ zakladania nie je preferovaný a slúži len pre jednoduché aplikácie typu darovania peňazí.

Kde nájdem príklady v PHP?

Príklady v PHP nájdete na stránke dokumentácie API.

Čo znamená parameter test?

Parameter test u platby rozhoduje, či sa jedná len o simuláciu úhrady, alebo reálnu úhradu napr. platobnou kartou. Typicky bude použitý pred nasadením do produkcie pre otestovanie funkčnosti platobnej brány na konkrétnej platbe.

Ako nastaviť e-mail pre zasielanie chýb?

V klientskom portáli v sekcii „Integrácia“ > „Kontaktné údaje“ je vhodné nastaviť si e-mail pre zasielanie chýb. Viac adries môžete oddeliť bodkočiarkou. Developer potom obdrží chyby (napr. chybnú kombináciu meny a platobnej metódy) z API priamo na e-mail.

Kde nájdem zoznam povolených metód v API?

Aktuálne metódy doporučujeme sťahovať vždy pri vygenerovaní košíka platcovi. Môžete ich získať API volaním – viď dokumentácia.

Ako môže správca organizácie zakladať pre svojho vývojára prihlasovacie údaje?

Správca organizácie môže zakladať pre svojho vývojára prihlasovacie údaje v klientskom portáli v sekcii „Spravovanie používateľov“ a potom „Pridať používateľa“.

Je e-mail pri založení transakcie povinný? Aké inštrukcie prídu platcovi na e-mail?

Ku každej platbe vyžadujeme vyplnenie e-mailu. Či už zo strany e-shopu pri zakladaní platby alebo následne od platcu pri zobrazení platobnej brány. Pre zjednodušenie úhrady platcovi doporučujeme vyplniť e-mail priamo z e-shopu. Na e-mail platcovi zašleme odkaz pre zobrazenie stavu jeho platby. Zároveň môže pomocou zaslaného odkazu znova skúsiť predchádzajúcu neúspešnú úhradu.

Ako sa dá overiť stav platby?

Jediný bezpečný spôsob, ako si overiť stav platby, je pomocou zavolania API metódy – viď dokumentáciu.

Ako sa dostanem do testovacích log/testovacích platieb?

Testovacie logá/testovacie platby sú prístupné, pokiaľ má používateľ právo Tester (po nastavení nových práv používateľa je potrebné sa znova prihlásiť).

Čo sa stane, pokiaľ nie je potvrdené prevzatie výsledku na pozadie http kódom 200?

Pokiaľ nie je potvrdené prevzatie výsledku na pozadie HTTP kódom 200, vyvolá to opakované odovzdanie do max. počtu 1000 pokusov. Pokiaľ sa ani po 1000 pokusoch (rozložených v čase) nepodarilo odovzdať stav platby do e-shopu, vygenerujeme e-mail o chybe a zašleme ho e-shopu.

Ako postupovať pri opakovaných platbách?

Pri opakovaných platbách je kód 1500 spoločný pre nezaplatenie a aj chybu. Doporučujeme opakovať pokus o zaplatenie maximálne 5x s určitým časovým odstupom (napr. kvôli dennému limitu na účte) a potom vytvoriť novú iniciačnú platbu. Opakované platby nemusia byť realizované z rôznych dôvodov – nedostatok prostriedkov na karte platcu, prekročený limit úhrad atď.

Kto iniciuje opakovanie platby pri opakovaných platbách?

Pri opakovaných platbách iniciuje opakovanie platby vždy e-shop. Prvá platba je iniciačná, tú musí platca uhradiť. Následne už opakovaná platba prebieha bez jeho účasti.

Ako postupovať, pokiaľ má e-shop viac jazykových mutácií?

Pokiaľ má e-shop viac jazykových mutácií na viacerých URL adresách (napr. cz.eshop.com a sk.eshop.com), môže si vytvoriť viac prepojení obchodu a tam definovať rozdielne návratové URL. Každá mutácia e-shopu musí byť nahlásená asociáciám platobných kariet. Pokiaľ sa celá komunikácia s platobnou bránou odohráva v jednom e-shope, stačí len jediné ohlásenie asociáciám platobných kariet. Väčšie prepojenie obchodu je možné použiť napr. aj pri migrácii e-shopu na novú e-shopovú platformu alebo vytvorenie testovacej verzie e-shopu.

Ako vypnúť IP whitelist? 

Niektoré hostingy používajú pre odchádzajúce konekcie iné IP, naviac ich môžu náhodne rotovať. Preto je dobré kontaktovať správcu hostingu, aby poskytol všetky možné IP v odchádzajúcom smere, ktoré sa potom zapíšu do IP whitelistu. Poskytovatelia hostingu často uverejňujú zoznamy IP adries na webe.

Prečo nepodporujete IPv6? 

IPv6 nie je možné zadať. Používame IPv4 whitelist, kde je uvedená informácia, z akej IP adresy môže e-shop komunikovať s našim API.

Podporujete Google Analytics? 

Google Analytics nepodporujeme. Bližšie informácie si môžete prečítať v tomto článku. 

Kedy sa robí presmerovanie do e-shopu na URL pre stav PAID? 

Presmerovanie do e-shopu na URL pre stav PAID prebieha do jednej hodiny od založenia platby. Hneď ako platca pristúpi na platobnú bránu neskôr ako hodinu od založenia platby, brána už ho do e-shopu sama aktívne nepresmeruje. Dôvodom je skutočnosť, že platca často pristupuje z iného zariadenia (napr. z telefónu) na stav platby aj po dlhšej časovej odozve. V e-shope by už teda nemusela byť aktívna session s objednávkou.

Do akého parametra sa má ukladať číslo objednávky z e-shopu? 

Do parametra refId ukladajte ideálne číslo objednávky, aby bolo možné vykonať párovanie CSV/ABO do účtovníctva.

Je možné implementovať platobnú bránu v PHP 5?

Na stiahnutie je aj táto ukážka zastaralej implementácie v PHP 5. Pokiaľ je to možné, doporučujeme použiť SDK (vyššie).