Protokol API

API dokumentace

Podrobnou dokumentaci API najdete na tomto odkazu. Slouží pro vlastní implementaci napojení e-shopu na API. Obsahuje ukázky CURL, PHP, JAVA a Python requestů. 

PHP Software development kit (PHP SDK)

Pro snadnou implementaci platební brány můžete použít tento PHP SDK (instalace přes composer).

Časté otázky

Kde najdu přihlašovací údaje do API?

Přihlašovací údaje najdete v klientském portálu v sekci „Integrace“ > „Nastavení obchodu“ a poté „Propojení obchodu“.

Co je login a co heslo do API?

Login je identifikátor propojení obchodu (ve většině případů šestimístné číslo) a heslo náleží k tomuto identifikátoru. Oba tyto údaje jsou uvedeny v klientském portálu  v sekci „Integrace“ > „Nastavení obchodu“ > „Propojení obchodu“.

Co je založení na pozadí vs. založení přesměrováním a proč je založení na pozadí lepší?

Založení platby na pozadí slouží pro bezpečné a garantované založení platby s parametry, které korespondují s e-shopovou objednávkou. Plátce tedy nemůže ovlivnit např. cenu, musí ji celou uhradit. Oproti tomu založení přesměrováním se používá např. pro dary, u kterých může plátce libovolně měnit cenu platby. V naprosté většině případů tedy doporučujeme založení platby na pozadí (volání z e-shopu na API Comgate).

Proč není dobré začít implementaci v SOAP?

SOAP podporujeme z historických důvodů a již se nevyvíjí, proto není dobré v něm začít implementaci.

Jak nastavit IP whitelist?

API Comgate je chráněno pomocí IP whitelistu. U každého e-shopu evidujeme IP adresy, ze kterých lze komunikovat s naším API. Přidání povolených IP adres můžete provést v klientském portálu  „Integrace“ > „Nastavení obchodu“ a poté „Propojení obchodu“. Kontaktujte správce svého hostingu a získejte všechny IP adresy v odchozím směru, ze kterých mohou vaše servery komunikovat. Poskytovatelé hostingu často uveřejňují seznamu IP adres na webu. V případě, že má váš server dynamickou IP adresu, můžete kontrolu IP whitelistu v klientském portálu vypnout. V případě tohoto nastavení věnujte maximální pozornost zabezpečení komunikačního hesla. 

Co se má nastavit v PENDING, PAID a CANCELLED URL v propojení obchodu?

Je třeba vyplnit URL, pokud používáte HTTP POST nebo REST protokol (u SOAPU není nutné). První tři URL slouží k přesměrování uživatele, poslední URL slouží k předání výsledku na pozadí. Bez správně nastaveného URL se e-shop o výsledku transakce nemusí dozvědět. V případě, že nevyplníte „pending URL“, na platební bráně se nebude zobrazovat tlačítko „Návrat do e-shopu“. PENDING, PAID a CANCELLED URL jsou adresy na endpointy v e-shopu, kam přesměrujeme plátce z platební brány, pokud dojde například k úspěšné úhradě platby. URL pro předání výsledku platby slouží pro komunikaci našeho API s e-shopem (předání výsledku platby do e-shopu).

Jak nastavit URL?

Je třeba vyplnit URL, pokud používáte HTTP POST nebo REST protokol (u SOAPU není nutné). První tři URL slouží k přesměrování uživatele, poslední URL slouží k předání výsledku na pozadí. Bez správně nastaveného URL se e-shop o výsledku transakce nemusí dozvědět. V případě, že nevyplníte „pending URL“, na platební bráně se nebude zobrazovat tlačítko „Návrat do e-shopu“.

Jak nastavit založení přesměrováním?

Založení přesměrováním je potřeba nejprve povolit v propojení obchodu v klientském portálu „Integrace“ > „Nastavení obchodů“ > „Propojení obchodu“. Není potřeba vyplňovat IP whitelist a není nutné posílat heslo při zakládání požadavku. Tento typ zakládání není preferován a slouží pouze pro jednoduché aplikace typu darování peněz.

Kde najdu příklady v PHP?

Příklady v PHP najdete na stránce API dokumentace.

Co znamená parametr test?

Parametr test u platby rozhoduje, zda se jedná pouze o simulaci úhrady, nebo reálnou úhradu např. platební kartou. Typicky bude použit před nasazením do produkce pro otestování fukčnosti platební brány na konkrétní platbě.

Jak nastavit e-mail pro zasílání chyb?

V klientském portálu v sekci „Integrace“ > „Kontaktní údaje“ je vhodné si nastavit e-mail pro zasílání chyb. Více adres můžete oddělit středníkem. Developer pak obdrží chyby (např. špatnou kombinaci měny a platební metody) z API rovnou na e-mail.

Kde najdu seznam povolených metod v API?

Doporučujeme aktuální metody stahovat vždy při vygenerování košíku plátci. Můžete je získat API voláním – viz tuto dokumentaci.

Jak může správce organizace zakládat pro svého vývojáře přihlašovací údaje?

Správce organizace může zakládat pro svého vývojáře přihlašovací údaje v klientském portálu v sekci „Správa uživatelů“ a poté „Přidat uživatele“.

Je e-mail při založení transakce povinný? Jaké instrukce plátci na e-mail přijdou?

Ke každé platbě vyžadujeme vyplnění e-mailu. Ať už ze strany e-shopu při zakládání platby nebo následně od plátce při zobrazení platební brány. Pro zjednodušení úhrady plátci doporučujeme vyplnit e-mail přímo z e-shopu. Na e-mail plátci zašleme odkaz pro zobrazení stavu jeho platby. Zároveň může promocí zaslaného odkazu znovu zkusit dřívější neúspěšnou úhradu.

Jak se dá ověřit stav platby?

Jediný bezpečný způsob, jak si ověřit stav platby, je pomocí zavolání API metody – viz tuto dokumentaci.

Jak se dostanu do testovacích logů/testovacích plateb?

Testovací logy/testovací platby jsou přístupné, pokud má uživatel právo Tester (po nastavení nových práv uživatele je potřeba se znovu přihlásit).

Co se stane, pokud není potvrzeno převzetí výsledku na pozadí http kódem 200?

Pokud není potvrzeno převzetí výsledku na pozadí HTTP kódem 200, vyvolá to opakování předání do max. počtu 1000 pokusů. Pokud se ani po 1000 pokusech (rozložených v čase) nepodařilo předat stav platby do e-shopu, vygenerujeme chybový e-mail a zašleme ho e-shopu.

Jak postupovat u opakovaných plateb?

U opakovaných plateb je kód 1500 společný pro nezaplacení i chybu. Doporučujeme opakovat pokus o zaplacení maximálně 5x s určitým časovým odstupem (např. kvůli dennímu limitu na účtu) a poté vytvořit novou iniciační platbu. Opakované platby nemusí být realizovány z různých důvodů – nedostatek prostředků na kartě plátce, překročený limit úhrad atd.

Kdo iniciuje opakování platby u opakovaných plateb?

U opakovaných plateb iniciuje opakování platby vždy e-shop. První platba je iniciační, tu musí plátce uhradit. Následně již opakovaná platba probíhá bez jeho účasti.

Jak postupovat, pokud má e-shop více jazykových mutací?

Pokud má e-shop více jazykových mutací na více URL adresách (např. cz.eshop.com a sk.eshop.com), může si vytvořit více propojení obchodu a tam definovat odlišné návratové URL. Každá mutace e-shopu musí být nahlášena karetním asociacím. Pokud se veškerá komunikace s platební bránou odehrává v jednom e-shopu, stačí pouze jediné ohlášení karetním asociacím. Více propojení obchodu lze použít např. i při migraci e-shopu na novou e-shopovou platformu nebo vytvoření testovací verze e-shopu.

Proč nepodporujete IPv6? 

IPv6 nelze zadat. Používáme IPv4 whitelist, kde je uvedena informace, z jaké IP adresy může e-shop komunikovat s naším API.

Podporujete Google Analytics? 

Google Analytics nepodporujeme. Bližší informace se lze dočíst v tomto článku.

Kdy se dělá přesměrování do e-shopu na URL pro stav PAID? 

Přesměrování do e-shopu na URL pro stav PAID probíhá do jedné hodiny od založení platby. Jakmile plátce přistoupí na platební bránu později než hodinu od založení platby, brána už ho do e-shopu sama aktivně nepřesměruje. Důvodem je skutečnost, že plátce často přistupuje z jiného zařízení (např. z telefonu) na stav platby i po delší časové prodlevě. V e-shopu by již tedy nemusela být aktuální session s objednávkou.

Do jakého parametru se má ukládat číslo objednávky z e-shopu? 

Do parametru refId ukládejte ideálně číslo objednávky, aby bylo možné provést párování CSV/ABO do účetnictví.

Je možné implementovat platební bránu v PHP 5?

Ke stažení je i tato ukázka zastaralé implementace v PHP 5. Pokud je to možné, doporučujeme použít SDK (výše).