Skip to main content

Konfigurácia a správa platobnej brány

Tento dokument slúži ako ucelený sprievodca pre automatizovanú správu a konfiguráciu platobných brán Comgate prostredníctvom rozhrania API.

1. Účel a cieľová skupina​

Endpoint /v1.0/config je pokročilé rozhranie určené napríklad pre partnerov typu „Developer“ (SaaS platformy, e-shopové riešenia), ktorí spravujú veľké portfólio klientskych e-shopov. Umožňuje programovo (hromadne) konfigurovať parametre platobných brán bez nutnosti manuálneho nastavovania v klientskom portáli Comgate. To zaisťuje konzistenciu brandingu a automatizáciu onboardingu nových klientov.

2. Autentizačný proces (Auth Flow)​

Získanie prístupu k endpointu prebieha v niekoľkých krokoch, aby bola zaistená maximálna bezpečnosť:

  1. Developer Credentials: Partner dostane pri podpise zmluvy svoje hlavné identifikačné údaje: developer a secret.
  2. Získanie zoznamu merchantov: Partner zavolá endpoint /v1.0/merchants so svojimi údajmi.
  • Výstup: JSON zoznam všetkých e-shopov pod jeho správou, obsahujúci merchant_id, unikátny merchant_secret a ďalšie informácie pre každý obchod.
  1. Konfigurácia: Práve kombináciu konkrétneho Merchant ID a jeho Merchant Secret využije partner v tele požiadavky na endpoint /v1.0/config.
Upozornenie

Poznámka: Pre použitie endpointu /merchants je potrebné kontaktovať našu zákaznícku podporu, ktorá developerovi vygeneruje potrebné prístupové údaje (developer a secret) a aktivuje príslušné oprávnenia.

3. Kľúčové parametre a funkcie endpointu /v1.0/merchants​

Tento endpoint je prvým krokom pre akúkoľvek automatizáciu. Slúži na získanie aktuálneho zoznamu všetkých obchodov, ktoré sú pod správou partnera.

Prehľad parametrov:

ParameterVýznamFormát / Príklad
developerID developeradeveloper1234
secretHeslo developeraM3hZVScYZKq9t...

Príklad implementácie:

// Request
$I->sendPost("https://payments.comgate.cz/v1.0/merchants",
[
    'developer' => 'your_developer_id',
    'secret' => 'your_developer_secret'
]);

Prehľad response parametrov:

ParameterVýznamFormát / Príklad
merchantID konkrétneho obchodu123456
secretTajný kľúč daného obchodu (pre ďalšiu konfiguráciu)M3hZVScYZKq9t...
allowed_payment_creation_methodPovolené spôsoby založenia platby pre daný obchodREST/POST
shopNázov e-shopueshop.sk
urlURL e-shopuhttps://eshop.sk/
contract_statusAktuálny stav zmluvyAKTIVNI
store_in_productionIdentifikácia, či je obchod už v produkciitrue / false
reported_to_card_schemesInformácia o tom, či bol obchod nahlásený kartovým asociáciám (Visa/Mastercard)true / false
currenciesZoznam podporovaných mien pre daný obchodPole (array) mien (napr. ["CZK", "EUR"])
ip_addressesZoznam povolených IP adries pre komunikáciu s APIPole IP adries (napr. ["185.123.45.67", "185.123.45.68"])
  • Parameter allowed_payment_creation_method môže nadobúdať tieto hodnoty:
    • REST/POST – Obchod môže zakladať platby pomocou REST API alebo HTTP POST
    • SOAP – Obchod môže zakladať platby pomocou SOAP API
    • REDIRECT – Obchod môže zakladať platby iba presmerovaním zákazníka na platobnú bránu (bez API)
  • Parameter contract_status môže nadobúdať tieto hodnoty:
    • ZALOZENA – Novozaložená zmluva, kde nie sú doriešené niektoré náležitosti
    • AKTIVNI – Všetky náležitosti sú splnené a zmluvu je možné aktivovať. Je nutné kontrolovať parametre reported_to_card_schemes a store_in_production, kvôli ktorým sa aktivácia môže zdržať, pretože eshop nie je plne v súlade s podmienkami pre aktiváciu služieb (chýbajúce OP a pod.).
    • UKONCENA - Zmluva byla ukončena.
  • Parameter store_in_production môže nadobúdať tieto hodnoty:
    • true – Obchod je už aktívny v produkcii
    • false – Čaká sa na prepnutie obchodu do produkčného stavu
  • Parameter reported_to_card_schemes môže nadobúdať tieto hodnoty:
    • true – Obchod bol nahlásený platobným asociáciám
    • false – Čaká sa na nahlásenie obchodu platobným asociáciám
Upozornenie

Poznámka: Parametre povoleny_zpusob_zalozeni_platby, stav_smlouvy, obchod_v_produkci a ohlaseno nebudú od 31. 7. 2026 naďalej vrátené v API odpovedi. Tieto parametre nahradili ich ekvivalenty allowed_payment_creation_method, contract_status, store_in_production a reported_to_card_schemes.

// Response
{
    "0": {
        "merchant": "123456",
        "secret": "M3hZVScYZKq9t...",
        "allowed_payment_creation_method": "REST/POST",
        "shop": "eshop.sk",
        "url": "https://eshop.sk/",
        "contract_status": "AKTIVNI",
        "store_in_production": true,
        "reported_to_card_schemes": true,
        "currencies": [
            "CZK",
            "EUR"
        ],
        "ip_addresses": [
            "185.123.45.67", 
            "185.123.45.68"
        ]
    },
    "code": 0,
    "message": "OK"
}

4. Kľúčové parametre a funkcie endpointu /v1.0/config​

V rámci volania je možné definovať vizuálny štýl, logiku notifikácií a bezpečnostné pravidlá.

Prehľad parametrov:

ParameterVýznamFormát / Príklad
merchantID konkrétneho konfigurovaného obchodu123456
secretTajný kľúč daného obchodu (získaný cez /v1.0/merchants)M3hZVScYZKq9t...
gateway_logoLogo e-shopu zobrazené na bráneBase64 string
gateway_backgroundObrázok pozadia zobrazený na bráneBase64 string
gateway_color_pageHlavná farba podfarbenia brányHEX kód (napr. #C2E7FF)
gateway_color_headerFarba záhlavia brányHEX kód (napr. #f2c7af)
gateway_signatureText zobrazený v pätičke brányPoskytované Platformou XY
url_paidURL na presmerovanie po úspešnej platbehttps://eshop.sk/success
url_cancelledURL na presmerovanie po zrušení platbyhttps://eshop.sk/cancel
url_pendingURL na presmerovanie pre nevybavenú platbuhttps://eshop.sk/pending
url_pushURL na zasielanie automatických notifikácií o platbehttps://eshop.sk/push.php
ip_addressesZoznam povolených IP adries pre komunikáciu s APIPole (array) IP adries
activeSlúži na deaktiváciu prepojenianull / false
  • Parameter ip_addresses umožňuje definovať povolené IP adresy.
    • Hodnota {} odstráni všetky IP adresy (zablokovanie prístupu)
    • Hodnota null ponechá pôvodné IP adresy
    • Konkrétna IP adresa/zoznam IP adries nahradí predchádzajúce nastavenie novým rozsahom IP adries

5. Bezpečnosť a IP Whitelist​

Zabezpečenie komunikácie medzi platformou a platobnou bránou je postavené na whitelistingu IP adries.

Workflow nastavenia:

  1. Iniciácia: Aby bolo možné vykonať konfiguráciu obchodu cez API, musí mať daný obchod dočasne nastavený rozsah povolených IP adries 0.0.0.0/0 (t. j. povolený prístup odkiaľkoľvek). Platforma tak môže vykonať úvodné volanie potrebné pre vytvorenie a nastavenie prepojenia.
  2. Zaistenie: Ihneď po aktivácii je povinnosťou developera poslať požiadavku na /v1.0/config a v poli ip_addresses definovať konkrétne IP adresy svojich serverov.
  3. Uzamknutie: Akonáhle je whitelist nastavený, brána odmietne akúkoľvek požiadavku z neautorizovanej adresy, čím eliminuje riziko útoku.

6. Príklad konfigurácie​

// Request
$I->sendPost("https://payments.comgate.cz/v1.0/config",
[
    'merchant' => 123456,                    // ID konkrétného obchodu
    'secret' => 'M3hZVScYZKq9tRjsftjasdg...', // Secret konkrétného obchodu
    'gateway_logo' => 'base64_encoded_image',
    'gateway_color_page' => '#C2E7FF',
    'gateway_signature' => 'Poskytované Platformou XY',
    'url_paid' => 'https://eshop.sk/success',
    'url_push' => 'https://eshop.sk/push.php',
    'ip_addresses' => ['185.123.45.67', '185.123.45.68'], // Whitelist serverov platformy
]);