Konfigurace a správa platební brány

Tento dokument slouží jako ucelený průvodce pro automatizovanou správu a konfiguraci platebních bran Comgate prostřednictvím rozhraní API.

1. Účel a cílová skupina

Endpoint /v1.0/config je pokročilé rozhraní určené například pro partnery typu „Developer“ (SaaS platformy, e-shopová řešení), kteří spravují velké portfolio klientských e-shopů. Umožňuje programově (hromadně) konfigurovat parametry platebních bran bez nutnosti ručního nastavování v klientském portálu Comgate. To zajišťuje konzistenci brandingu a automatizaci onboardingu nových klientů.

2. Autentizační proces (Auth Flow)

Získání přístupu k endpointu probíhá v několika krocích, aby byla zajištěna maximální bezpečnost:

Developer Credentials: Partner obdrží při podpisu smlouvy své hlavní identifikační údaje: developer a secret.
Získání seznamu merchantů: Partner zavolá endpoint /v1.0/merchants se svými údaji.

Výstup: JSON seznam všech e-shopů pod jeho správou, obsahující merchant_id, unikátní merchant_secret a další informace pro každý obchod.

Konfigurace: Právě kombinaci konkrétního Merchant ID a jeho Merchant Secret využije partner v těle požadavku na endpoint /v1.0/config.

Upozornění

Poznámka: Pro použití endpointu /merchants je potřeba kontaktovat naši zákaznickou podporu, která developerovi vygeneruje potřebné přístupové údaje (developer a secret) a aktivuje příslušná oprávnění.

3. Klíčové parametry a funkce endpointu `/v1.0/merchants`

Tento endpoint je prvním krokem pro jakoukoliv automatizaci. Slouží k získání aktuálního seznamu všech obchodů, které jsou pod správou partnera.

Přehled parametrů:

Parametr	Význam	Formát / Příklad
developer	ID developera	`developer1234`
secret	Heslo developera	`M3hZVScYZKq9t...`

Příklad implementace:

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

Přehled response parametrů:

Parametr	Význam	Formát / Příklad
merchant	ID konkrétního obchodu	`123456`
secret	Tajný klíč daného obchodu (pro další konfiguraci)	`M3hZVScYZKq9t...`
allowed_payment_creation_method	Povolené způsoby založení platby pro daný obchod	`REST/POST`
shop	Název e-shopu	`eshop.cz`
url	URL e-shopu	`https://eshop.cz/`
contract_status	Aktuální stav smlouvy	`AKTIVNI`
store_in_production	Identifikace, zda je obchod již na produkci	`true` / `false`
reported_to_card_schemes	Informace o tom, zda byl obchod ohlášen u karetních asociací (Visa/Mastercard)	`true` / `false`
currencies	Seznam podporovaných měn pro daný obchod	Pole (array) měn (např. `["CZK", "EUR"]`)
ip_addresses	Seznam povolených IP adres pro komunikaci s API	Pole IP adres (např. `["185.123.45.67", "185.123.45.68"]`)

Parametr allowed_payment_creation_method může nabývat těchto hodnot:
- REST/POST – Obchod může zakládat platby pomocí REST API nebo HTTP POST
- SOAP – Obchod může zakládat platby pomocí SOAP API
- REDIRECT – Obchod může zakládat platby pouze přesměrováním zákazníka na platební bránu (bez API)
Parametr contract_status může nabývat těchto hodnot:
- ZALOZENA – Nově založená smlouva, kde nejsou dořešeny nějaké náležitosti
- AKTIVNI – Všechny náležitosti jsou splněny a smlouvu lze aktivovat. Je nutné kontrolovat parametry reported_to_card_schemes a store_in_production, kvůli kterým se aktivace může zdržet, protože eshop není plně v souladu s podmínkami pro aktivaci služeb (chybějící OP, apod.).
- UKONCENA - Smlouva byla ukončena.
Parametr store_in_production může nabývat těchto hodnot:
- true – Obchod je již aktivní v produkci
- false – Čeká se na přepnutí obchodu do produkčního stavu
Parametr reported_to_card_schemes může nabývat těchto hodnot:
- true – Obchod byl ohlášen u platebních asociací
- false – Čeká se na ohlášení obchodu u platebních asociací

Upozornění

Poznámka: Parametry povoleny_zpusob_zalozeni_platby, stav_smlouvy, obchod_v_produkci a ohlaseno nebudou od 31. 7. 2026 nadále vráceny v API odpovědi. Tyto parametry nahradily jejich 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.cz",
        "url": "https://eshop.cz/",
        "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. Klíčové parametry a funkce endpointu `/v1.0/config`

V rámci volání lze definovat vizuální styl, logiku notifikací a bezpečnostní pravidla.

Přehled parametrů:

Parametr	Význam	Formát / Příklad
merchant	ID konkrétního konfigurovaného obchodu	`123456`
secret	Tajný klíč daného obchodu (získaný přes `/v1.0/merchants`)	`M3hZVScYZKq9t...`
gateway_logo	Logo e-shopu zobrazené na bráně	Base64 string
gateway_background	Obrázek pozadí zobrazený na bráně	Base64 string
gateway_color_page	Hlavní barva podbarvení brány	HEX kód (např. `#C2E7FF`)
gateway_color_header	Barva záhlaví brány	HEX kód (např. `#f2c7af`)
gateway_signature	Text zobrazený v patičce brány	`Poskytováno Platformou XY`
url_paid	URL pro přesměrování po úspěšné platbě	`https://eshop.cz/success`
url_cancelled	URL pro přesměrování po zrušené platbě	`https://eshop.cz/cancelled`
url_pending	URL pro přesměrování po nedokončené platbě	`https://eshop.cz/pending`
url_push	URL pro zasílání automatických notifikací o platbě	`https://eshop.cz/push.php`
ip_addresses	Seznam povolených IP adres pro komunikaci s API	Pole (array) IP adres
active	Slouží k deaktivaci propojení	`null` / `false`

Parametr ip_addresses umožňuje definovat povolené IP adresy.
- Hodnota {} odstraní všechny IP adresy (zablokování přístupu)
- Hodnota null ponechá původní IP adresy
- Konkrétní IP adresa/seznam IP adres nahradí předchozí nastavení na nový rozsah IP adres

5. Bezpečnost a IP Whitelist

Zabezpečení komunikace mezi platformou a platební bránou je postaveno na whitelistingu IP adres.

Workflow nastavení:

Iniciace: Aby bylo možné provést konfiguraci obchodu přes API, musí mít daný obchod dočasně nastavený rozsah povolených IP adres 0.0.0.0/0 (tj. povolený přístup odkudkoliv). Platforma tak může provést úvodní volání potřebné pro vytvoření a nastavení propojení.
Zajištění: Ihned po aktivaci je povinností developera poslat požadavek na /v1.0/config a v poli ip_addresses definovat konkrétní IP adresy svých serverů.
Uzamčení: Jakmile je whitelist nastaven, brána odmítne jakýkoliv požadavek z neautorizované adresy, čímž eliminuje riziko útoku.

6. Příklad konfigurace

// 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' => 'Poskytováno Platformou XY',
    'url_paid' => 'https://eshop.cz/success',
    'url_push' => 'https://eshop.cz/push.php',
    'ip_addresses' => ['185.123.45.67', '185.123.45.68'], // Whitelist serverů platformy
]);

1. Účel a cílová skupina​

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

3. Klíčové parametry a funkce endpointu /v1.0/merchants​

4. Klíčové parametry a funkce endpointu /v1.0/config​

5. Bezpečnost a IP Whitelist​

6. Příklad konfigurace​