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 /v2.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ť:

Developer Credentials: Partner dostane pri podpise zmluvy svoje hlavné identifikačné údaje: developer a secret.
Získanie zoznamu merchantov: Partner zavolá endpoint /v2.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.

Konfigurácia: Práve kombináciu konkrétneho Merchant ID a jeho Merchant Secret využije partner v tele požiadavky na endpoint /v2.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 `/v2.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:

Parameter	Význam	Formát / Príklad
developer	ID developera	`developer1234`
secret	Heslo developera	`M3hZVScYZKq9t...`

Príklad implementácie:

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

Prehľad response parametrov:

Parameter	Význam	Formát / Príklad
merchant	ID konkrétneho obchodu	`123456`
secret	Tajný kľúč daného obchodu (pre ďalšiu konfiguráciu)	`M3hZVScYZKq9t...`
allowed_payment_creation_method	Povolené spôsoby založenia platby pre daný obchod	`REST/POST`
shop	Názov e-shopu	`eshop.sk`
url	URL e-shopu	`https://eshop.sk/`
contract_status	Aktuálny stav zmluvy	`AKTIVNI`
store_in_production	Identifikácia, či je obchod už v produkcii	`true` / `false`
reported_to_card_schemes	Informácia o tom, či bol obchod nahlásený kartovým asociáciám (Visa/Mastercard)	`true` / `false`
currencies	Zoznam podporovaných mien pre daný obchod	Pole (array) mien (napr. `["CZK", "EUR"]`)
ip_addresses	Zoznam povolených IP adries pre komunikáciu s API	Pole 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 `/v2.0/config`

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

Prehľad parametrov:

Parameter	Význam	Formát / Príklad
merchant	ID konkrétneho konfigurovaného obchodu	`123456`
secret	Tajný kľúč daného obchodu (získaný cez `/v2.0/merchants`)	`M3hZVScYZKq9t...`
gateway_logo	Logo e-shopu zobrazené na bráne	Base64 string
gateway_background	Obrázok pozadia zobrazený na bráne	Base64 string
gateway_color_page	Hlavná farba podfarbenia brány	HEX kód (napr. `#C2E7FF`)
gateway_color_header	Farba záhlavia brány	HEX kód (napr. `#f2c7af`)
gateway_signature	Text zobrazený v pätičke brány	`Poskytované Platformou XY`
url_paid	URL na presmerovanie po úspešnej platbe	`https://eshop.sk/success`
url_cancelled	URL na presmerovanie po zrušení platby	`https://eshop.sk/cancelled`
url_pending	URL na presmerovanie pri čakajúcej platbe	`https://eshop.sk/pending`
url_push	URL na zasielanie automatických notifikácií o platbe	`https://eshop.sk/push.php`
ip_addresses	Zoznam povolených IP adries pre komunikáciu s API	Pole (array) IP adries
active	Slúži na deaktiváciu prepojenia	`null` / `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:

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.
Zaistenie: Ihneď po aktivácii je povinnosťou developera poslať požiadavku na /v2.0/config a v poli ip_addresses definovať konkrétne IP adresy svojich serverov.
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

$I->sendPost("https://payments.comgate.cz/v2.0/config",
[
    '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
]);

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

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

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

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

5. Bezpečnosť a IP Whitelist​

6. Príklad konfigurácie​