Configuration and Management of the Payment Gateway

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

1. Purpose and Target Audience

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

2. Authentication Process (Auth Flow)

Access to the endpoint is obtained in several steps to ensure maximum security:

Developer Credentials: The partner receives their primary identification credentials—developer and secret—upon signing the contract.
Obtaining the Merchant List: The partner calls the /v2.0/merchants endpoint using 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 then uses the specific combination of the Merchant ID and its Merchant Secret in the request body for the /v2.0/config endpoint.

Warning

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

3. Key parameters and functions of the `/v2.0/merchants` endpoint

This endpoint is the first step for any automation. It is used to retrieve the current list of all stores under the partner's management.

Parameter overview:

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

Implementation example:

// Request
$I->sendGet("https://payments.comgate.cz/v2.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.cz`
url	E-shop URL	`https://eshop.cz/`
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 Terms and Conditions).
- 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.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. Key parameters and functions of the `/v2.0/config` endpoint

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

Parameter overview:

Parameter	Meaning	Format / Example
merchant	ID of the specific store being configured	`123456`
secret	Secret key of the given store (obtained via `/v2.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	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	Redirect URL after a successful payment	`https://eshop.cz/success`
url_cancelled	Redirect URL after a cancelled payment	`https://eshop.cz/cancelled`
url_pending	Redirect URL for a pending payment	`https://eshop.cz/pending`
url_push	URL for sending automatic payment notifications	`https://eshop.cz/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 permitted 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 range of IP addresses.

5. Security and IP Whitelisting

Securing the communication between the platform and the payment gateway is based on IP address whitelisting.

Setup Workflow:

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

6. Configuration Example

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

1. Purpose and Target Audience​

2. Authentication Process (Auth Flow)​

3. Key parameters and functions of the /v2.0/merchants endpoint​

4. Key parameters and functions of the /v2.0/config endpoint​

5. Security and IP Whitelisting​

6. Configuration Example​