Payment Gateway Configuration and Management

This document serves as a comprehensive guide for the automated management and configuration of Comgate payment gateways via the API.

1. Purpose and Target Group

The /v1.0/config endpoint is an advanced interface designed, for example, for partners of the "Developer" type (SaaS platforms, e-shop solutions) who manage a large portfolio of client e-shops. It allows for the programmatic (bulk) configuration of payment gateway parameters without the need for manual setup in the Comgate client portal. This ensures branding consistency and automates the onboarding of new clients.

2. Authentication Process (Auth Flow)

Gaining access to the endpoint takes place in several steps to ensure maximum security:

Developer Credentials: Upon signing the contract, the partner receives their main identification data: developer and secret.
Obtaining the Merchant List: The partner calls the /v1.0/merchants endpoint with their credentials.

Output: A JSON list of all e-shops under their management, containing the merchant_id, a unique merchant_secret, and other information for each store.

Configuration: The partner uses the combination of the specific Merchant ID and its Merchant Secret in the request body for the /v1.0/config endpoint.

Warning

Note: To use the /merchants endpoint, you must contact our customer support, who will generate the necessary access credentials (developer and secret) for the developer and activate the corresponding permissions.

3. Key Parameters and Functions of the `/v1.0/merchants` Endpoint

This endpoint is the first step for any automation. It is used to retrieve the current list of all stores managed by the partner.

Parameter Overview:

Parameter	Meaning	Format / Example
developer	Developer ID	`developer1234`
secret	Developer Password	`M3hZVScYZKq9t...`

Implementation Example:

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

Response parameter overview:

Parameter	Meaning	Format / Example
merchant	ID of the specific store	`123456`
secret	Secret key of the given store (for further configuration)	`M3hZVScYZKq9t...`
allowed_payment_creation_method	Permitted methods for creating a payment for the given store	`REST/POST`
shop	E-shop name	`eshop.com`
url	E-shop URL	`https://eshop.com/`
contract_status	Current contract status	`AKTIVNI`
store_in_production	Identification of whether the store is already in production	`true` / `false`
reported_to_card_schemes	Information on whether the store has been reported to card associations (Visa/Mastercard)	`true` / `false`
currencies	List of supported currencies for the given store	Array of currencies (e.g., `["CZK", "EUR"]`)
ip_addresses	List of allowed IP addresses for API communication	Array of IP addresses (e.g., `["185.123.45.67", "185.123.45.68"]`)

The allowed_payment_creation_method parameter can take the following values:
- REST/POST – The store can create payments using REST API or HTTP POST.
- SOAP – The store can create payments using SOAP API.
- REDIRECT – The store can only create payments by redirecting the customer to the payment gateway (without API).
The contract_status parameter can take the following values:
- ZALOZENA – A newly created contract where certain requirements are still being finalized.
- AKTIVNI – All requirements are met and the contract can be activated. It is necessary to monitor the reported_to_card_schemes and store_in_production parameters, as activation may be delayed if the e-shop is not fully compliant with the service activation terms (e.g., missing T&Cs, etc.).
- UKONCENA - The contract was terminated.
The store_in_production parameter can take the following values:
- true – The store is already active in production.
- false – Waiting for the store to be switched to production status.
The reported_to_card_schemes parameter can take the following values:
- true – The store has been reported to payment associations.
- false – Waiting for the store to be reported to payment associations.

Warning

Note: The parameters povoleny_zpusob_zalozeni_platby, stav_smlouvy, obchod_v_produkci, and ohlaseno will no longer be returned in the API response as of July 31, 2026. These parameters have been replaced by their equivalents: allowed_payment_creation_method, contract_status, store_in_production, and reported_to_card_schemes.

// Response
{
    "0": {
        "merchant": "123456",
        "secret": "M3hZVScYZKq9t...",
        "allowed_payment_creation_method": "REST/POST",
        "shop": "eshop.com",
        "url": "https://eshop.com/",
        "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. Key Parameters and Functions of the `/v1.0/config` Endpoint

Within this call, you can define the visual style, notification logic, and security rules.

Parameter Overview:

Parameter	Description	Format / Example
merchant	ID of the specific configured store	`123456`
secret	Secret key of the store (obtained via `/v1.0/merchants`)	`M3hZVScYZKq9t...`
gateway_logo	E-shop logo displayed on the gateway	Base64 string
gateway_background	Background image displayed on the gateway	Base64 string
gateway_color_page	Main background color of the gateway page	HEX code (e.g., `#C2E7FF`)
gateway_color_header	Gateway header color	HEX code (e.g., `#f2c7af`)
gateway_signature	Text displayed in the gateway footer	`Powered by Platform XY`
url_paid	Redirection URL after a successful payment	`https://eshop.com/success`
url_cancelled	Redirection URL after a cancelled payment	`https://eshop.com/cancel`
url_pending	Redirection URL for a pending payment	`https://eshop.com/pending`
url_push	URL for sending automated payment notifications	`https://eshop.com/push.php`
ip_addresses	List of allowed IP addresses for API communication	Array of IP addresses
active	Used to deactivate the connection	`null` / `false`

The ip_addresses parameter allows you to define allowed IP addresses.
- A value of {} removes all IP addresses (blocking access).
- A value of null keeps the original IP addresses.
- A specific IP address or a list of IP addresses replaces the previous settings with the new IP range.

5. Security and IP Whitelisting

Communication security between the platform and the payment gateway is built on IP address whitelisting.

Setup Workflow:

Initiation: To enable store configuration via the API, the specific store must temporarily have the allowed IP range set to 0.0.0.0/0 (i.e., access allowed from anywhere). This allows the platform to perform the initial call required to create and set up the connection.
Securing: Immediately after activation, it is the developer's responsibility to send a request to /v1.0/config and define the specific IP addresses of their servers in the ip_addresses field.
Locking: Once the whitelist is set, the gateway will reject any request from an unauthorized address, thereby eliminating the risk of an attack.

6. Configuration Example

// Request
$I->sendPost("https://payments.comgate.cz/v1.0/config",
[
    'merchant' => 123456,                
    'secret' => 'M3hZVScYZKq9tRjsftjasdg...', 
    'gateway_logo' => 'base64_encoded_image',
    'gateway_color_page' => '#C2E7FF',
    'gateway_signature' => 'Powered by Platform XY',
    'url_paid' => 'https://eshop.com/success',
    'url_push' => 'https://eshop.com/push.php',
    'ip_addresses' => ['185.123.45.67', '185.123.45.68'], 
]);

1. Purpose and Target Group​

2. Authentication Process (Auth Flow)​

3. Key Parameters and Functions of the /v1.0/merchants Endpoint​

4. Key Parameters and Functions of the /v1.0/config Endpoint​

5. Security and IP Whitelisting​

6. Configuration Example​