V REST variante API podporujeme iba dátové formáty JSON a XML. Formát multipart/form-data nie je podporovaný.
Prístup je chránený validáciou IP adresy a integrita odovzdávaných dát je zabezpečená použitím HTTPS protokolu.
Server platobnej brány zodpovedá len v prípade, že je platba zakladaná na pozadí. Všetky parametre sú 'urlencoded', rovnako ako v prípade HTTP requestu. Ak je platba založená presmerovaním, potom server platobnej brány rovno presmeruje Platiteľ na príslušnú URL alebo zobrazí chybové hlásenie.
Výber platobnej metódy
V rámci nákupného procesu v e-shope je možné zobraziť plátcovi výber platebných metód a na základe jeho výberu založiť platbu s konkrétnou metódou. V momente, keď je plátcovi zobrazená platobná brána, automaticky sa zobrazí predom vybraná platobná metóda. Nastavenie vybranej platobnej metódy je možné vyplnením parametra 'method'. Prostredníctvom tohto parametra je možné platobné metódy aj rôzne filtrovať.
Viac tu: https://apidoc.comgate.cz/sk/metody-platebni-brany/
Predautorizácia
Platobná brána umožňuje zadávať, potvrdzovať a rušiť predautorizácie platieb kartou. Založenie platby sa uskutočňuje štandardne, len je potrebné uviesť parameter 'preauth = true'. Potom platca prejde rovnakým procesom ako v prípade normálnej platby. Potom, čo zadá svoje údaje na platobnej bráne, je na jeho platobnej karte rezervovaná príslušná suma. Podľa výsledku tejto operácie prechádza buď do zvláštneho stavu Authorized, alebo v prípade zamietnutia do stavu CANCELLED. Tento stav je ohlásený na pozadí obvyklým postupom opísaným vyššie.
Aby boli peniaze skutočne strhnuté, vyvolá e-shop funkciu na potvrdenie predautorizácie. Ak sa peniaze majú uvoľniť (napr. nie je možné naplniť podmienky kúpnej zmluvy), vyvolá funkciu na zrušenie predautorizácie.
Presmerovanie
Pre zakladanie platby presmerovaním použite endpoint /v2.0/paymentRedirect/merchant/{merchant_id}, s rovnakými parametrami ako pri základnej create.
Adresa URL a štruktúra kódu platby sa môže zmeniť. Vždy používajte adresu vrátenú rozhraním API a nemanipulujte s ňou. Ak chcete platobný kód uložiť, použite parameter transId. Nikdy neparazitujte na údajoch z konkrétnych pozícií v texte, tie sa tiež môžu zmeniť.
Všetky hodnoty obsahujúce špeciálne znaky musia byť v UTF-8.
authorization required | string Autorizačná hlavička je v tvare:: 'Authorization: Basic [base64_encode(merchant:secret)]'. Merchant je identifikátor e-shopu v systéme Comgate - nájdete v Klientskom portáli v sekcii Nastavenie obchodov - Prepojenie obchodu. Secret je heslo. |
Vytvorenie novej platby
test | boolean Default: false Hodnota 'true' znamená, že platba bude založená ako testovacia, hodnota 'false' znamená produkčnú verziu. Ak parameter chýba, založí sa platba ako produkčná. |
country | string Možné hodnoty: ALL, AT, BE, CY, CZ, DE, EE, EL, ES, FI, FR, GB, HR, HU, IE, IT, LT, LU, LV, MT, NL, NO, PL, PT , RO, SI, SK, SE, US. Ak parameter chýba, použije sa automaticky 'CZ'. Parameter slúži na obmedzenie výberu platobných metód na platobnej bráne. Je potrebné aby bola zvolená správna kombinácia parametrov 'country' a 'curry' (mena) pre daný región. Napríklad na zobrazenie českých tlačidiel a platby kartou v mene CZK zvoľte kombináciu country = CZ a curry = CZK. Pri slovenských bankových tlačidlách a platbe kartou v EUR zvoľte country = SK a curry = EUR. Pre poľské bankové tlačidlá a platbu kartou v PLN zvoľte country = PL a curry = PLN. Pre ostatné cudzie meny môžete použiť parameter country = ALL alebo ďalší kód krajiny, ktorý platobná brána prijíma. |
price required | integer <int32> Cena za výrobok v centoch alebo halieroch. Pre menu HUF nemôžete zadať cenu s desatinnými miestami. V tomto prípade musí cena vždy končiť 00. |
curr required | string Kód meny podľa ISO 4217. K dispozícii sú meny: EUR, CZK, PLN, HUF, USD, GBP, RON, NOK, SEK. |
label required | string Krátky opis produktu (1-16 znakov) - podľa tejto položky je možné filtrovať platby v Klientskom portáli. |
refId required | string Parameter vhodný na zadanie variabilného symbolu alebo čísla objednávky na strane Klienta (nemusí byť unikátne, tzn., že možno založiť viac platieb s rovnakým refid). V Klientskom portáli a denným csv. je parameter označený ako ID Klienta. |
method required | string Metóda platby z tabuľky platobných metód, hodnota 'ALL' v prípade, že si má metódu vybrať platiteľa alebo jednoduchý výraz s výberom metód. |
account | string Identifikátor bankového účtu Klienta, na ktorý Comgate prevedie peniaze. Ak parameter nevyplníte, použije sa predvolený účet Klienta. Zoznam účtov Klienta nájdete na https://portal.comgate.cz/. |
email required | string Kontaktný email platiteľa. Povinný je len jeden z údajov, emailová adresa alebo telefónne číslo. |
phone required | string Telefónne číslo platiteľa v medzinárodnom formáte +420777112233. Povinný je len jeden z údajov, emailová adresa alebo telefónne číslo. |
fullName required | string Meno a priezvisko plátcu, napr. Josef Novák. |
billingAddrCity | string Fakturačná adresa - mesto. (napr. Hradec Králové). |
billingAddrStreet | string Fakturačná adresa - ulica. (napr. Jiráskova 115). |
billingAddrPostalCode | string Fakturačná adresa - PSČ. (napr. 50304). |
billingAddrCountry | string Fakturačná adresa - krajina, vo formáte ISO 3166 alpha-2 (napr. CZ, SK, US, GB). |
delivery | string Spôsob doručenia - jedna z dostupných možností: HOME_DELIVERY, PICKUP, ELECTRONIC_DELIVERY. Možnosť PICKUP zahŕňa všetky miesta na vyzdvihnutie, vyzdvihovacie boxy, atď. |
homeDeliveryCity | string Doručovacia adresa - mesto. Vyplňuje sa len v prípade delivery=HOME_DELIVERY (napr. Hradec Králové). |
homeDeliveryStreet | string Doručovacia adresa - ulica. Vyplňuje sa len v prípade delivery=HOME_DELIVERY (napr. Štefanikova 421). |
homeDeliveryPostalCode | string Doručovacia adresa - PSČ. Vyplňuje sa len v prípade delivery=HOME_DELIVERY (napr. 50341). |
homeDeliveryCountry | string Doručovacia adresa - krajina, vo formáte ISO 3166 alpha-2. Vyplňuje sa len v prípade delivery=HOME_DELIVERY (napr. CZ, SK, US, GB). |
category | string Kategória produktu v košíku - jedna z dostupných možností, ktorá najlepšie opisuje košík: PHYSICAL_GOODS_ONLY, OTHER. Možnosť OTHER zahŕňa darčekové karty, poukážky alebo služby. |
name | string Identifikátor produktu - táto položka sa nachádza v dennom csv. Klienta pod názvom Produkt. |
lang | string Kód jazyka (ISO 639-1), v ktorom budú Platiteľovi zobrazené inštrukcie na dokončenie platby, štandardne povolené hodnoty ('bg', 'cs', 'da', 'de', 'el', 'en', 'es', 'et', 'fi', 'fr', 'hr', 'hu', 'it', 'lt', 'lv', 'nl', 'no', 'pl', 'pt', 'ro', 'si', 'sk', 'sv', 'vi'), ak parameter chýba, použije sa 'cs' v prípade požiadavky na ďalší jazyk, kontaktujte podpora@comgate.cz. |
preauth | boolean V prípade požiadavky na predautorizáciu platby kartou nastavte na 'true'. V prípade normálnej platby vyplňte 'false' alebo parameter nepoužívajte. Len na platby kartou. |
initRecurring | boolean Príznak pre založenie iniciačnej transakcie pre opakované platby. Len pre Klientov, ktorí majú službu povolenú. |
verification | boolean Parameter overovacej platby, v prípade požiadavky na založenie overovacej platby (hodnota 'true') nie je nutné posielať parameter 'initRecurring'. |
expirationTime | string Délka expirace platby. Povolená hodnota je celé číslo následované písmenem zvolené časové jednotky: 'm' (minuty), 'h' (hodiny) nebo 'd' (dny). Například '30m' (30 minut) nebo '10h' (10 hodin) nebo '2d' (2 dny). Jednotky nelze kombinovat. Výsledná délka musí být v rozmezí 30 minut až 7 dní. Pokud není vyplněno, použije se hodnota v nastavení obchodu zvolená v Klientském portálu. |
dynamicExpiration | boolean Hodnota 'true' znamená, že u platby bude použita dynamická expirace, hodnota 'false' znamená, že dynamická expirace použita nebude. Pokud není vyplněno, použije se hodnota v nastavení obchodu zvolená v Klientském portálu. |
url_paid | string Posamezne nastavitve za posamezna plačila. Na primer: 'https://www.example.com/result.php?id=${id}&refId=${refId}' |
url_cancelled | string Posamezne nastavitve za posamezna plačila. Na primer: 'https://www.example.com/result.php?id=${id}&refId=${refId}' |
url_pending | string Posamezne nastavitve za posamezna plačila. Na primer: 'https://www.example.com/result.php?id=${id}&refId=${refId}' |
chargeUnregulatedCardFees | boolean Pomocou tohto parametra zapnete alebo vypnete prenos poplatkov na platiteľa pri platbe neregulovanou kartou a zároveň vypnete metódu Apple Pay a Google Pay (ak nie je parametrom 'enableApplePayGooglePay' nastavené inak). Povolené hodnoty sú 'true' alebo 'false'. |
enableApplePayGooglePay | boolean Nastavte na 'false' pre vypnutie platobnej metódy Apple Pay a Google Pay pre konkrétnu platbu, aj keď sú tieto metódy vo vašom nastavení účtu povolené. |
code required | integer Návratový kód metódy a opis chyby: |
message required | string |
transId | string Unikátny alfanumerický identifikátor (kód) transakcie, ktorý bude zobrazený Platiteľmi v rôznych fázach platby. |
redirect | string URL stránka, kam má byť Platiteľ presmerovaný na realizáciu platby. |
{- "test": true,
- "country": "string",
- "price": 1000,
- "curr": "CZK",
- "label": "Product 123",
- "refId": "order445566",
- "method": "ALL",
- "account": "string",
- "email": "platce@email.com",
- "phone": "string",
- "fullName": "Jan Novák",
- "billingAddrCity": "string",
- "billingAddrStreet": "string",
- "billingAddrPostalCode": "string",
- "billingAddrCountry": "string",
- "delivery": "HOME_DELIVERY",
- "homeDeliveryCity": "string",
- "homeDeliveryStreet": "string",
- "homeDeliveryPostalCode": "string",
- "homeDeliveryCountry": "string",
- "category": "PHYSICAL_GOODS_ONLY",
- "name": "string",
- "lang": "string",
- "preauth": true,
- "initRecurring": true,
- "verification": true,
- "expirationTime": "string",
- "dynamicExpiration": true,
- "url_paid": "string",
- "url_cancelled": "string",
- "url_pending": "string",
- "chargeUnregulatedCardFees": true,
- "enableApplePayGooglePay": true
}
{- "code": 0,
- "message": "OK",
- "transId": "AB12-CD34-EF56",
}
Storno platby
V prípade, že bola objednávka v e-shope stornovaná a transakcia nemá byť platcom dokončená, je možné využiť storno platby. Na rozdiel od refundácie musí byť platba v stave očakávaná (pending).
Vzhľadom na rýchlosť zaplatenia platieb môže byť platba už v stave zaplatená, v takom prípade sa zobrazí chyba a je nutné využiť metódu refundácie.
transId required | string Example: AAAA-BBBB-CCCC unikátny alfanumerický identifikátor (kód) transakcie (transactionId) |
authorization required | string Autorizačná hlavička je v tvare:: 'Authorization: Basic [base64_encode(merchant:secret)]'. Merchant je identifikátor e-shopu v systéme Comgate - nájdete v Klientskom portáli v sekcii Nastavenie obchodov - Prepojenie obchodu. Secret je heslo. |
code required | integer návratový kód metódy a opis chyby: |
message required | string |
# You can also use wget curl -X DELETE https://payments.comgate.cz/v2.0/payment/transId/{transId}.json \ -H 'Authorization: Basic MTIzNDU2Omd4NHE4T1YzVEp0Nm5vSm5maGpxSkt5WDNaNlljaDB5'
{- "code": 0,
- "message": "OK"
}
Získanie stavu platby na pozadí
Analogická funkcia pre odovzdanie výsledku platby na pozadí, iba iniciovaná Obchodom. Nenahrádza však odovzdanie stavu platby na pozadí, jej implementácia je stále povinná.
transId required | string Example: AAAA-BBBB-CCCC unikátny alfanumerický identifikátor (kód) transakcie (transactionId) |
authorization required | string Autorizačná hlavička je v tvare:: 'Authorization: Basic [base64_encode(merchant:secret)]'. Merchant je identifikátor e-shopu v systéme Comgate - nájdete v Klientskom portáli v sekcii Nastavenie obchodov - Prepojenie obchodu. Secret je heslo. |
code required | integer Návratový kód metódy |
message required | string návratový kód metódy a opis chyby: |
test required | string Hodnota 'true' znamená, že platba bola založená ako testovacia, hodnota 'false' znamená produkčnú verziu. |
price required | integer cena za výrobok v centoch alebo halieroch |
curr required | string kód meny podľa ISO 4217 |
label required | string krátky opis produktu (1 – 16 znakov) |
refId required | string referencia platby v systéme e-shopu |
payerId | string identifikátor Platiteľa v systéme e-shopu |
method | string použitá metóda platby, z tabuľky platobných metód |
account | string identifikátor bankového účtu e-shopu, na ktorý Comgate prevedie peniaze |
email required | string kontaktný email na Platiteľa |
name | string Identifikátor produktu - podľa tejto položky je potom možné sa zorientovať v štatistikách platieb Comgate platobného systému. |
phone | string Telefonska številka plačnika, če je na voljo |
transId required | string unikátny alfanumerický identifikátor (kód) transakcie (transactionId) |
status required | string aktuálny stav transakcie, hodnoty |
payerName | string odovzdanie mena účtu patriacemu Platiteľovi |
payerAcc | string odovzdanie čísla účtu Platiteľa |
fee | string ak má e-shop nastavené automatické strhávanie poplatku za platbu, bude v tomto poli spočítaný poplatok za transakciu v centoch alebo halieroch, inak bude pole nadobúdať hodnotu 'unknown' |
vs | string variabilný symbol platby (nie je vždy k dispozícii) |
cardValid | string expirácia karty platiteľa dostupná pri opakovaných iniciačných platbách okrem Apple Pay a Google Pay |
cardNumber | string čiastočné číslo karty platiteľa dostupné pri opakovaných iniciačných platbách |
appliedFee | integer Výška príplatku aplikovaná za neregulované typy kariet. |
appliedFeeType | string Typ príplatku aplikovaného za neregulované typy kariet ako je 'EU_UNREGULATED', 'NON_EU_BUSINESS', 'NON_EU_CONSUMER' aj nepríplatkový 'EU_CONSUMER'. |
paymentErrorReason | string Dôvod zamietnutia platby, ak je k dispozícii. V prípade viacerých pokusov platiteľa o vykonaní platby sa vracia dôvod zamietnutia posledného pokusu. Možné hodnoty: |
# You can also use wget curl -X GET https://payments.comgate.cz/v2.0/payment/transId/{transId}.json \ -H 'Authorization: Basic MTIzNDU2Omd4NHE4T1YzVEp0Nm5vSm5maGpxSkt5WDNaNlljaDB5'
{- "code": 0,
- "message": "OK",
- "test": false,
- "price": 10000,
- "curr": "CZK",
- "label": "Beatles - Help",
- "refId": "2010102600",
- "payerId": "string",
- "method": "ALL",
- "account": "string",
- "email": "platce@email.com",
- "name": "string",
- "phone": "string",
- "transId": "AB12-CD34-EF56",
- "status": "PAID",
- "payerName": "string",
- "payerAcc": "string",
- "fee": "string",
- "vs": "string",
- "cardValid": "string",
- "cardNumber": "string",
- "appliedFee": 0,
- "appliedFeeType": "string",
- "paymentErrorReason": "string"
}
Opakované platby, zapamätanie kartových údajov
Platobná brána umožňuje zadávanie opakovaných platieb, t.j. platieb na jedno kliknutie. Prvá (iniciačná) platba sa uskutočňuje štandardným procesom s presmerovaním na platobnú bránu, nasledujúce platby sa už uskutočňujú kompletne na pozadí. Systém tak umožňuje platcovi zaplatiť v priebehu niekoľkých sekúnd bez nutnosti vypĺňať informácie o platobnej karte.
Táto funkcia je dostupná na vyžiadanie. V prípade opakovaných platieb na začiatku zakladáme iniciačnú platbu, ktorá sa zakladá ako bežná platba, len sa v požiadavke nachádza navyše parameter 'initRecurring' - metóda create. Následné opakované platby sú už zakladané metódou recurring a sú viazané na Comgate ID iniciačnej transakcie. Toto ID musí byť v systéme Klienta viazané na konkrétneho Platiteľa.
Po založení opakovanej platby nedochádza k presmerovaniu platcu na platobnú bránu, pretože celý proces sa uskutočňuje na pozadí, Klientovi je len odovzdaný stav založenia platby a ten následne zobrazí tento stav platcovi.
Nasledujúce opakované platby
Založenie druhej a nasledujúcej opakované platby do platobnej brány je možné len pri akceptácii kariet pre e-shopy, ktoré majú službu povolenú. Prvá (iniciačná) platba sa uskutočňuje štandardnou cestou (pozri Založenie platby). Proces založenia druhej a každej ďalšej platby sa uskutočňuje kompletne na pozadí, tieto platby sú viazané na iniciačné cez Comgate ID iniciačné platby. Toto ID sa musí nachádzať v požiadavke v parametri 'initRecurringId'. Platiteľovi je v systéme e-shopu ako výsledok zobrazený stav platby.
Všetky parametre sú urlencoded, rovnako ako v prípade HTTP requestu na založenie štandardnej platby. V odpovedi sa nachádza parameter 'code', podľa ktorého e-shop určí, aký výsledok zobrazí platcovi. code = 0 znamená úspech, platba bola vytvorená a zaplatená, akýkoľvek iný kód znamená chybu a teda nezaloženie platby.
Rekurentné platby (recurring)
Rekurentné platby, tzn. opakované platby s vopred zadefinovanou sumou a periódou (napr. mesačné, týždenné apod.) je možné realizovať pomocou služby Opakované platby, ktorá je opísaná v predchádzajúcich odsekoch.
Testovacie opakované platby (okrem iniciačných) vytvorené pomocou e-mailu 'recurring.cancelled@comgate.cz' budú automaticky označené ako CANCELLED (nezaplatené)
authorization required | string Autorizačná hlavička je v tvare:: 'Authorization: Basic [base64_encode(merchant:secret)]'. Merchant je identifikátor e-shopu v systéme Comgate - nájdete v Klientskom portáli v sekcii Nastavenie obchodov - Prepojenie obchodu. Secret je heslo. |
test | boolean Hodnota 'true' znamená, že platba bude založená ako testovacia, hodnota 'false' znamená, že platba bude založená ako produkčná verzia. Ak parameter chýba, založí sa platba ako produkčná. |
price required | integer <int32> Cena za výrobok v centoch alebo halieroch. Musí byť min. 10 CZK (vrátane), max. neobmedzene. |
curr required | string kód meny podľa ISO 4217, štandardne 'CZK' |
label required | string krátky opis produktu (1 – 16 znakov) |
refId required | string Referencia platby v systéme e-shopu (nemusí byť unikátna, tzn., že možno založiť viac platieb s rovnakým refid). |
account | string Identifikátor bankového účtu e-shopu, na ktorý Comgate prevedie peniaze. Ak parameter nevyplníte, použije sa predvolený účet e-shopu. Zoznam účtov e-shopu nájdete na https://portal.comgate.cz/ |
name | string Identifikátor produktu - podľa tejto položky je potom možné sa zorientovať v štatistikách platieb Comgate platobného systému. |
initRecurringId required | string Comgate ID iniciačnej platby |
code required | integer Návratový kód metódy a opis chyby: |
message required | string |
transId | string unikátny alfanumerický identifikátor (kód) transakcie, ktorý bude zobrazený Platiteľmi v rôznych fázach platby |
{- "test": true,
- "price": 10000,
- "curr": "CZK",
- "label": "string",
- "refId": "2010102600",
- "account": "string",
- "name": "string",
- "initRecurringId": "AB12-CD34-EF56"
}
{- "code": 0,
- "message": "OK",
- "transId": "string"
}
Refundácia platby
Metóda pre refundáciu je určená pre už založené a preplatené platby. Stav platby musí byť zaplatená (paid). Je možné vykonať ako čiastočnú (refundovaná suma je nižšia ako suma platby), tak plnú refundáciu (suma refundácie je rovnaká ako suma platby). Daná čiastka bude prevedená späť na účet platiteľa.
Ak platba nebola dokončená a je v stave pending, je možné využiť metódu storno platby.
authorization required | string Autorizačná hlavička je v tvare:: 'Authorization: Basic [base64_encode(merchant:secret)]'. Merchant je identifikátor e-shopu v systéme Comgate - nájdete v Klientskom portáli v sekcii Nastavenie obchodov - Prepojenie obchodu. Secret je heslo. |
Vrátenie platby
transId required | string unikátny alfanumerický identifikátor (kód) transakcie (transactionId) |
amount required | integer <int32> čiastka refundácie - môže byť v plnej alebo čiastočnej výške transakcie. Suma refundácie sa zadáva v centoch alebo halieroch. Pre menu HUF nie je možné zadať sumu s desatinnými miestami. V tomto prípade musí suma vždy končiť 00. |
test | boolean Hodnota 'true' znamená, že refundácia bude založená ako testovacia. Refundácia a platba bude preverená štandardnou cestou, len nedôjde k refundácii pôvodnej platby. |
refId | string Parameter vhodný na zadanie identifikačného čísla refundácie na strane Klienta (nemusí byť unikátna, tzn., že možno založiť viac refundácií s rovnakým refid); v Klientskom portáli v sekcii refundácií a denných csv pri refundácii je parameter označený ako ID Klienta. V prípade, že tento parameter na refundáciu nie je pripojený, k platbe sa zobrazí pôvodná refid založenej platby. |
code required | integer návratový kód metódy a opis chyby: |
message required | string |
{- "transId": "AB12-CD34-EF56",
- "amount": 10000,
- "test": true,
- "refId": "string"
}
{- "code": 0,
- "message": "OK"
}
Refundácia terminálovej platby
Metóda pre refundáciu je určená pre už založené a preplatené terminálové platby. Stav platby musí byť zaplatená (paid). Je možné vykonať ako čiastočnú (refundovaná suma je nižšia ako suma platby), tak plnú refundáciu (suma refundácie je rovnaká ako suma platby). Daná čiastka bude prevedená späť na účet platiteľa.
Ak platba nebola dokončená a je v stave pending, je možné využiť metódu storno platby. Serverové API nemusia mať záznam o platbe ihneď k dispozícii. Preto je vhodné najskôr zavolať refundáciu z pokladne na termináli. A volanie API využiť v prípade, že nemožno refundáciu zavolať z pokladne na termináli.
Pre využitie tejto metódy je nutné najskôr v Klientskom portáli nastaviť v sekcii Nastavenie obchodu - Terminály pri danom termináli povolenej IP adresy, z ktorých sa budú refundácie vykonávať.
authorization required | string Autorizačná hlavička je v tvare:: 'Authorization: Basic [base64_encode(merchant:secret)]'. Merchant je identifikátor e-shopu v systéme Comgate - nájdete v Klientskom portáli v sekcii Nastavenie obchodov - Prepojenie obchodu. Secret je heslo. |
Refundácia terminálovej platby
vs required | string variabilný symbol platby |
amount required | integer <int32> čiastka refundácie - môže byť v plnej alebo čiastočnej výške transakcie |
date required | string dátum vykonania transakcie |
code required | integer návratový kód metódy a opis chyby: |
message required | string |
{- "vs": "7654321",
- "amount": 10000,
- "date": "2000-02-22"
}
{- "code": 0,
- "message": "OK"
}
V prípade, že e-shop založil platbu s požiadavkou na predautorizáciu platby kartou (s využitím parametra 'preauth = true'), vyvolaním tejto funkcie vyžiada strhnutie peňazí, ktoré boli v rámci predautorizácie zablokované. Je možné vykonať ako čiastočné strhnutie transakcie (predautorizovaná suma je nižšia ako suma platby), tak plné strhnutie (suma strhnutia je rovnaká ako suma platby). Volanie možno použiť len na platby, pri ktorých bol ohlásený stav Authorized.
transId required | string Example: AAAA-BBBB-CCCC unikátny alfanumerický identifikátor (kód) transakcie (transactionId) |
authorization required | string Autorizačná hlavička je v tvare:: 'Authorization: Basic [base64_encode(merchant:secret)]'. Merchant je identifikátor e-shopu v systéme Comgate - nájdete v Klientskom portáli v sekcii Nastavenie obchodov - Prepojenie obchodu. Secret je heslo. |
Potvrdenie predbežnej autorizácie
amount | integer <int32> čiastka predautorizácie, ktorá má byť z karty strhnutá - môže byť v plnej alebo čiastočnej výške transakcie |
code required | integer návratový kód metódy a opis chyby: |
message required | string |
{- "amount": 10000
}
{- "code": 0,
- "message": "OK"
}
V prípade, že e-shop založil platbu s požiadavkou na predautorizáciu platby kartou (s využitím parametra 'preauth = true'), vyvolaním tejto funkcie dáva najavo, že peniaze, ktoré boli v rámci predautorizácie zablokované, nechce inkasovať a peniaze sa na karte môžu opäť uvoľniť. Volanie možno použiť len na platby, pri ktorých bol ohlásený stav Authorized.
transId required | string Example: AAAA-BBBB-CCCC unikátny alfanumerický identifikátor (kód) transakcie (transactionId) |
authorization required | string Autorizačná hlavička je v tvare:: 'Authorization: Basic [base64_encode(merchant:secret)]'. Merchant je identifikátor e-shopu v systéme Comgate - nájdete v Klientskom portáli v sekcii Nastavenie obchodov - Prepojenie obchodu. Secret je heslo. |
code required | integer návratový kód metódy a opis chyby: |
message required | string |
# You can also use wget curl -X DELETE https://payments.comgate.cz/v2.0/preauth/transId/{transId}.json \ -H 'Authorization: Basic MTIzNDU2Omd4NHE4T1YzVEp0Nm5vSm5maGpxSkt5WDNaNlljaDB5'
{- "code": 0,
- "message": "OK"
}
Metóda transferList slúži na získanie informácie, aké prevody boli uskutočnené v rámci daného dňa. Informacije o bančnem prenosu (poslanem prejšnji delovni dan) so na voljo v dopoldanskih urah naslednjega dne.
Prevody a výpisy sa generujú iba pre zaplatené a prevedené produkčné platby. Pre všetky ostatné platby, vrátane testovacích, sa prevody a výpisy negenerujú.
date required | string Example: 2025-04-25 uveďte dátum uskutočnenia prevodu |
test | boolean Example: test=false ak vyplníte true, metóda vráti vopred definovaný vzorový prevod |
authorization required | string Autorizačná hlavička je v tvare:: 'Authorization: Basic [base64_encode(merchant:secret)]'. Merchant je identifikátor e-shopu v systéme Comgate - nájdete v Klientskom portáli v sekcii Nastavenie obchodov - Prepojenie obchodu. Secret je heslo. |
transferId | integer Prevody, ktoré boli uskutočnené v rámci daného dňa. |
transferDate | string <date> Parametre date a transferDate sú interpretované v časovom pásme Europe/Prague (CET/CEST v závislosti od dátumu). |
accountCounterparty | string Číslo účtu protistrany. |
accountOutgoing | string Odchádzajúce číslo účtu. |
variableSymbol | string Identifikátor platby (variabilný symbol). |
# You can also use wget curl -X GET https://payments.comgate.cz/v2.0/transferList/date/{date}.json \ -H 'Authorization: Basic MTIzNDU2Omd4NHE4T1YzVEp0Nm5vSm5maGpxSkt5WDNaNlljaDB5'
[- {
- "transferId": 1234567,
- "transferDate": "2023-01-25",
- "accountCounterparty": "0/0000",
- "accountOutgoing": "123456789/0000",
- "variableSymbol": "12345678"
}
]
Metóda singleTransfer zobrazuje detailné informácie ku konkrétnemu bankovému prevodu.
Povinný parameter 'transferId' získa obchodník pomocou metódy transferList.
Dátumové parametre sa interpretujú v časovom pásme Europe/Prague (CET/CEST v závislosti od dátumu).
Prevody a výpisy sa generujú iba pre zaplatené a prevedené produkčné platby. Pre všetky ostatné platby, vrátane testovacích, sa prevody a výpisy negenerujú.
transferId required | string Example: 1234567 uveďte prevody, ktoré boli uskutočnené v rámci daného dňa. Zoznam získate pomocou metódy transferList. |
test | boolean Example: test=false vhodné na testovanie - Ak je hodnota true, vrátia sa detaily k vopred definovaným vzorovým prevodom |
authorization required | string Autorizačná hlavička je v tvare:: 'Authorization: Basic [base64_encode(merchant:secret)]'. Merchant je identifikátor e-shopu v systéme Comgate - nájdete v Klientskom portáli v sekcii Nastavenie obchodov - Prepojenie obchodu. Secret je heslo. |
typ | integer Parameter označuje typ prevodu. |
Merchant | string Identifikátor e-shopu v systéme Comgate. |
Datum založení | string Dátum založenia transakcie. |
Datum zaplacení | string Dátum zaplatenia transakcie. |
Datum převodu | string Dátum vyplatenia hromadného prevodu transakcií. |
Měsíc fakturace | integer Mesiac, ku ktorému sa platba účtovne vzťahuje. |
ID Comgate | string Comgate ID platby, 12-miestny kód, jedinečná identifikácia platby. |
Metoda | string Výsledná metóda platby. |
Produkt | string Ľubovoľný identifikátor produktu, ktorý váš systém posiela pri založení platby pod parametrom 'name'. |
Popis | string Krátky popis produktu (1–16 znakov), ktorý váš systém posiela pri založení platby pod parametrom 'label'. |
E-mail plátce | string E-mail platiteľa platby. |
Variabilní symbol platby | string Variabilný symbol pridelený platbe. |
Variabilní symbol převodu | string Variabilný symbol hromadného prevodu. |
ID od klienta | string Párovací symbol, pomocou ktorého identifikujete tovar a zákazníka, ktorý si ho objednal (napr. číslo objednávky, číslo zákazníka atď.). V rámci API protokolu je to parameter RefId, ktorý systém posiela pri založení platby. |
Měna | string Mena platby. Hodnota je vo formáte ISO 4217. |
Potvrzená částka | string Suma realizovanej transakcie (výška zákazníkovej objednávky). |
Převedená částka | string Suma, ktorá je e-shopu štandardne zaslaná na bankový účet (znížená o poplatok z transakcie). |
Poplatek celkem | string Celkový poplatok za platbu podľa platného cenníka. Poplatok celkom = medzibankový poplatok + poplatok asociácie + poplatok spracovateľa. |
Poplatek mezibankovní | string Poplatok, ktorý dostáva vydavateľ platobnej karty. |
Poplatek asociace | string Poplatok, ktorý z transakcie obdrží kartová asociácia. |
Poplatek zpracovatel | string Poplatok, ktorý si účtuje spracovateľ transakcie. |
Typ karty | string Typ použitej platobnej karty pri platbe kartou. |
# You can also use wget curl -X GET https://payments.comgate.cz/v2.0/singleTransfer/transferId/{transferId}.json \ -H 'Authorization: Basic MTIzNDU2Omd4NHE4T1YzVEp0Nm5vSm5maGpxSkt5WDNaNlljaDB5'
[- {
- "typ": 1,
- "Merchant": "123456",
- "Datum založení": "2023-01-06 14:11:30",
- "Datum zaplacení": "2023-01-06 14:21:30",
- "Datum převodu": "2023-01-10",
- "Měsíc fakturace": null,
- "ID Comgate": "AAAA-BBBB-CCCC",
- "Metoda": "Card payment",
- "Produkt": null,
- "Popis": "description eshop payment",
- "E-mail plátce": "name.lastname@email.cz",
- "Variabilní symbol platby": "123456789",
- "Variabilní symbol převodu": "123456789",
- "ID od klienta": "1234",
- "Měna": "EUR",
- "Potvrzená částka": "10,00",
- "Převedená částka": "10,00",
- "Poplatek celkem": "0,35",
- "Poplatek mezibankovní": "0,25",
- "Poplatek asociace": "0,25",
- "Poplatek zpracovatel": "-0,15",
- "Typ karty": "EU_UNREGULATED"
}
]
Vďaka metóde csvSingleTransfer si možno stiahnuť denný výpis vo formáte CSV.
Prevody a výpisy sa generujú iba pre zaplatené a prevedené produkčné platby. Pre všetky ostatné platby, vrátane testovacích, sa prevody a výpisy negenerujú.
transferId required | string Example: 1234567 Uveďte prevody, ktoré boli uskutočnené v rámci daného dňa. Zoznam získate pomocou metódy transferList. |
download | boolean Example: download=false Ak nie je vyplnené alebo je false, tak vracia dáta: názov súboru a jeho obsah; ak je true, tak vracia rovno CSV súbor. |
test | boolean Example: test=false Ak je hodnota true, vráti ukážkový CSV súbor. |
authorization required | string Autorizačná hlavička je v tvare:: 'Authorization: Basic [base64_encode(merchant:secret)]'. Merchant je identifikátor e-shopu v systéme Comgate - nájdete v Klientskom portáli v sekcii Nastavenie obchodov - Prepojenie obchodu. Secret je heslo. |
nazev | string Názov stiahnutého súboru CSV |
csv | string Súbor CSV s kódovaním Base64 |
# You can also use wget curl -X GET https://payments.comgate.cz/v2.0/csvSingleTransfer/transferId/{transferId}.json \ -H 'Authorization: Basic MTIzNDU2Omd4NHE4T1YzVEp0Nm5vSm5maGpxSkt5WDNaNlljaDB5'
{- "nazev": "vypis-YYYY-MM-DD.csv",
- "csv": "base64 encoded csv"
}
Vďaka metóde aboSingleTransfer si možno stiahnuť denný výpis vo formáte ABO.
Prevody a výpisy sa generujú iba pre zaplatené a prevedené produkčné platby. Pre všetky ostatné platby, vrátane testovacích, sa prevody a výpisy negenerujú.
transferId required | string Example: 1234567 uveďte prevody, ktoré boli uskutočnené v rámci daného dňa. Zoznam získate pomocou metódy transferList. |
download | boolean Example: download=true Ak nie je vyplnené alebo je false, tak vracia dáta: názov súboru a jeho obsah; ak je true, tak vracia rovno ABO súbor. |
type | string Example: type=v1 Parameter 'type' môže nadobúdať hodnoty 'v1' a ''v2'. Pod 'v1'' získate ABO verziu s poplatkami uvedenými zvlášť ku každej platbe, pod 'v2' potom ABO so súhrnným poplatkom v jednom riadku. Pokiaľ nebude parameter vyplnený, automaticky obdržíte typ 'v1'. |
encoding | string Example: encoding=false Kódovanie znakov môže byť utf8 alebo win1250. Ak hodnota nie je vyplnená, predvolená hodnota parametra je utf8. |
test | boolean Example: test=false Ak je hodnota true, vráti ukážkový ABO súbor. |
authorization required | string Autorizačná hlavička je v tvare:: 'Authorization: Basic [base64_encode(merchant:secret)]'. Merchant je identifikátor e-shopu v systéme Comgate - nájdete v Klientskom portáli v sekcii Nastavenie obchodov - Prepojenie obchodu. Secret je heslo. |
nazev | string názov súboru |
abo | string base64 kódovaný súbor abo/gpc |
# You can also use wget curl -X GET https://payments.comgate.cz/v2.0/aboSingleTransfer/transferId/{transferId}.json \ -H 'Authorization: Basic MTIzNDU2Omd4NHE4T1YzVEp0Nm5vSm5maGpxSkt5WDNaNlljaDB5'
{- "nazev": "vypis-YYYY-MM-DD.gpc",
- "abo": "base64_encoded_abo_file"
}
Priame preberanie CSV súborov pre konkrétny deň metódou csvDowload. Stiahnutý súbor vo formáte ZIP bude obsahovať jeden alebo viac súborov CSV, ak je viac prevodov v rámci dňa. Možno využiť napr. na volanie pomocou wget.
Prevody a výpisy sa generujú iba pre zaplatené a prevedené produkčné platby. Pre všetky ostatné platby, vrátane testovacích, sa prevody a výpisy negenerujú.
date required | string Example: 2025-04-25 povinný len za jeden deň |
test | boolean Example: test=false Ak je hodnota true, vráti ukážkový CSV súbor vo formáte ZIP. |
authorization required | string Autorizačná hlavička je v tvare:: 'Authorization: Basic [base64_encode(merchant:secret)]'. Merchant je identifikátor e-shopu v systéme Comgate - nájdete v Klientskom portáli v sekcii Nastavenie obchodov - Prepojenie obchodu. Secret je heslo. |
# You can also use wget curl -X GET https://payments.comgate.cz/v2.0/csvDownload/date/{date} \ -H 'Authorization: Basic MTIzNDU2Omd4NHE4T1YzVEp0Nm5vSm5maGpxSkt5WDNaNlljaDB5'
Priame preberanie ABO súborov pre konkrétny deň metódou aboDowload. Stiahnutý súbor vo formáte ZIP bude obsahovať jeden alebo viac súborov ABO.
Možno využiť napr. na volanie pomocou wget.
Prevody a výpisy sa generujú iba pre zaplatené a prevedené produkčné platby. Pre všetky ostatné platby, vrátane testovacích, sa prevody a výpisy negenerujú.
date required | string Example: 2025-04-25 povinný len za jeden deň |
type | string Parameter 'type' môže nadobúdať hodnoty 'v1' a ''v2'. Pod 'v1'' získate ABO verziu s poplatkami uvedenými zvlášť ku každej platbe, pod 'v2' potom ABO so súhrnným poplatkom v jednom riadku. Pokiaľ nebude parameter vyplnený, automaticky obdržíte typ 'v1'. |
encoding | string Kódovanie znakov môže byť utf8 alebo win1250. Ak hodnota nie je vyplnená, predvolená hodnota parametra je utf8. |
test | boolean Example: test=false Ak je hodnota true, vráti ukážkový CSV súbor vo formáte ZIP. |
authorization required | string Autorizačná hlavička je v tvare:: 'Authorization: Basic [base64_encode(merchant:secret)]'. Merchant je identifikátor e-shopu v systéme Comgate - nájdete v Klientskom portáli v sekcii Nastavenie obchodov - Prepojenie obchodu. Secret je heslo. |
# You can also use wget curl -X GET https://payments.comgate.cz/v2.0/aboDownload/date/{date} \ -H 'Authorization: Basic MTIzNDU2Omd4NHE4T1YzVEp0Nm5vSm5maGpxSkt5WDNaNlljaDB5'
Získanie povolených metód
Metóda na získanie nastavenia, ktoré má e-shop povolené v Comgate Platobnom Systéme. Touto metódou možno získať zoznam dostupných platobných metód na realizáciu platieb.
V odpovedi sa nachádza XML alebo JSON, podľa zvoleného parametra. Obidva formáty majú rovnakú úroveň zanorenia.
lang | string Výber, v akom jazyku budú opisy metód. Povolené hodnoty sú 'bg', 'cs', 'da', 'de', 'el', 'en', 'es', 'et', 'fi', 'fr', 'hr', 'hu', 'it', 'lt', 'lv', 'nl', 'no', 'pl', 'pt', 'ro', 'si', 'sk', 'sv', 'vi'. Pokiaľ nebude vyplnené, použije sa 'cs'. |
curr | string Vyplnením parametra na hodnoty CZK alebo EUR dôjde k vráteniu metód, ktoré podporujú zadanú menu (CZK, EUR, PLN, HUF, USD, GBP, RON, NOK, SEK). |
country | string Kód krajiny ('AT', 'BE', 'CY', 'CZ', 'DE', 'EE', 'EL', 'ES', 'FI', 'FR', 'GB', 'HR', 'HU', 'IE', 'IT', 'LT', 'LU', 'LV', 'MT', 'NL', 'NO', 'PL', 'PT', 'RO', 'SL', 'SK', 'SE', 'US'), parameter slúži na obmedzenie výberu možných spôsobov pre zadanú krajinu. |
price | integer Cena za výrobok v centoch alebo halieroch. Pre menu HUF nemôžete zadať cenu s desatinnými miestami. V tomto prípade musí cena vždy končiť 00. |
initRecurring | boolean Príznak pre iniciačnej transakcie pre opakované platby. Len pre Klientov, ktorí majú službu povolenú. |
verification | boolean Parameter overovacej platby, v prípade požiadavky na založenie overovacej platby (hodnota ‘true’) nie je nutné posielať parameter ‘initRecurring’. |
preauth | boolean V prípade požiadavky na predautorizáciu platby kartou nastavte na ‘true’. V prípade normálnej platby vyplňte ‘false’ alebo parameter nepoužívajte. Len na platby kartou. |
expirationTime | string Dĺžka expirácie platby. Povolená hodnota je celé číslo nasledované písmenom zvolenej časovej jednotky: 'm' (minúty), 'h' (hodiny) alebo 'd' (dni). Napríklad '30m' (30 minút) alebo '10h' (10 hodín) alebo '2d' (2 dni). Jednotky nemožno kombinovať. Výsledná dĺžka musí byť v rozmedzí 30 minút až 7 dní. |
embedded | boolean Parameter 'embedded' slúži na filtrovanie metód v prípade, že sa brána bude zobrazovať v iframe. Dôjde k odfiltrovaniu platobných metód, ktoré nie je možné na platobnej bráne v iframe zobraziť. Pokiaľ zobrazujete platobnú bránu v iframe, použite 'embedded=true'. |
userAgent | string Parameter 'userAgent' slúži na identifikáciu webového prehliadača zákazníka. Odfiltruje platobné metódy nekompatibilné s daným zariadením. |
chargeUnregulatedCardFees | boolean Pomocou tohto parametra zapnete alebo vypnete prenos poplatkov na platiteľa pri platbe neregulovanou kartou a zároveň vypnete metódu Apple Pay a Google Pay (ak nie je parametrom 'enableApplePayGooglePay' nastavené inak). Povolené hodnoty sú 'true' alebo 'false'. |
enableApplePayGooglePay | boolean Nastavte na 'false' pre vypnutie platobnej metódy Apple Pay a Google Pay pre konkrétnu platbu, aj keď sú tieto metódy vo vašom nastavení účtu povolené. |
authorization required | string Autorizačná hlavička je v tvare:: 'Authorization: Basic [base64_encode(merchant:secret)]'. Merchant je identifikátor e-shopu v systéme Comgate - nájdete v Klientskom portáli v sekcii Nastavenie obchodov - Prepojenie obchodu. Secret je heslo. |
required | Array of objects Dostupné metódy | ||||||||||||||||||||||||
Array
|
required | Array of objects Chyba | ||||||
Array
|
# You can also use wget curl -X GET https://payments.comgate.cz/v2.0/method.json \ -H 'Authorization: Basic MTIzNDU2Omd4NHE4T1YzVEp0Nm5vSm5maGpxSkt5WDNaNlljaDB5'
{- "methods": [
- {
- "id": "string",
- "group": "string",
- "groupLabel": "string",
- "name": "string",
- "name_short": "string",
- "description": "string",
- "logo": "string",
- "logo_240": "string",
- "cblogo": "string",
- "clogo": "string",
- "sblogo": "string",
- "slogo": "string"
}
]
}
Stiahnutie obsahu validačného súboru na overenie domény v Apple Pay pre Comgate Checkout SDK. Systém automaticky určí správny súbor podľa aktívnej kartovej metódy obchodníka. Viac informácií v implementačnom manuáli Checkout SDK.
currency | string Mena použitá na určenie validačného súboru. Hodnota je vo formáte ISO 4217. |
authorization required | string Autorizačná hlavička je v tvare:: 'Authorization: Basic [base64_encode(merchant:secret)]'. Merchant je identifikátor e-shopu v systéme Comgate - nájdete v Klientskom portáli v sekcii Nastavenie obchodov - Prepojenie obchodu. Secret je heslo. |
fileContent | string |
# You can also use wget curl -X GET https://payments.comgate.cz/v2.0/appleDomainAssociation.json \ -H 'Authorization: Basic MTIzNDU2Omd4NHE4T1YzVEp0Nm5vSm5maGpxSkt5WDNaNlljaDB5'
{- "fileContent": "APPLE_DOMAIN_ASSOCIATION_FILE_CONTENT_PLACEHOLDER"
}