Znojil Comgate

A simple and modern PHP library for communicating with the Comgate payment gateway API.

🚀 Installation

composer require znojil/comgate

📖 Usage

1. Client Initialization

use Znojil\Comgate\Client;
use Znojil\Comgate\Config;

$config = new Config(
	merchant: 'YOUR_MERCHANT_ID',
	secret: 'YOUR_SECRET',
	test: false // true for test mode
);

$client = new Client($config);

2. Creating a Payment

use Znojil\Comgate\DTO\PaymentDTO;
use Znojil\Comgate\Enum\Currency;
use Znojil\Comgate\Request\CreateRequest;

$payment = new PaymentDTO(
	price: 10000, // in cents, 10000 = 100.00 CZK
	curr: Currency::Czk,
	label: 'Order #1234',
	refId: 'order-1234',
	fullName: 'John Doe',
	email: 'john@example.com'
);

$result = $client->send(new CreateRequest($payment));

$result->transId; // AB12-CD34-EF56
$result->redirect; // redirect URL for payment gateway

If you prefer to redirect the customer directly to the payment gateway:

use Znojil\Comgate\Request\CreateRedirectRequest;

$redirectUrl = $client->send(new CreateRedirectRequest($payment));
// redirect the customer to $redirectUrl

3. Checking Payment Status

use Znojil\Comgate\Request\StatusRequest;

$status = $client->send(new StatusRequest('AB12-CD34-EF56'));

$status->transId; // AB12-CD34-EF56
$status->status; // PaymentStatus enum
$status->price; // int (cents)
$status->curr; // Currency enum

4. Using a Custom HTTP Client

You can inject your own HTTP client implementation by passing it as the second argument to the Client constructor. Your client must implement the Znojil\Comgate\Http\Client interface.

use Znojil\Comgate\Client;
use Znojil\Comgate\Http\Client as ComgateHttpClient;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\UriInterface;

class MyCustomHttpClient implements ComgateHttpClient{
	public function send(string $method, string|UriInterface $uri, array $headers = [], mixed $data = null, array $options = []): ResponseInterface{
		// your implementation
	}
}

$client = new Client($config, new MyCustomHttpClient);

Your implementation must honor the Znojil\Comgate\Http\Option::* keys passed in $options (e.g. Option::FollowRedirects — some requests rely on redirects not being followed automatically) and must reject unknown string keys with an exception. Integer keys are raw CURLOPT_* constants — non-cURL implementations must reject them with an exception rather than silently ignore them, so that a consumer never ends up with options that silently don't apply.

5. Handling Push Notifications

Comgate sends a push notification (HTTP POST) to your server when a payment status changes. Use Client::accept() to authenticate and process it:

use Znojil\Comgate\ServerRequest\PaymentStatusServerRequest;

$status = $client->accept(new PaymentStatusServerRequest);

$status->transId; // AB12-CD34-EF56
$status->status; // PaymentStatus enum
$status->price; // int (cents)
$status->curr; // Currency enum

accept() automatically validates the merchant and secret from the request body against your Config. If they do not match, an InvalidArgumentException is thrown.

You can also inject a PSR-7 ServerRequestInterface manually — useful in frameworks that provide it:

$status = $client->accept(new PaymentStatusServerRequest, $psrServerRequest);

⚠️ Error Handling

The client throws exceptions to help you identify the issue:

• Znojil\Comgate\Exception\ApiException: For API-level errors returned by Comgate (e.g. invalid parameters). Contains code and message from the API response.
• Znojil\Comgate\Exception\JsonResponseException: When an API response body is not valid JSON (subtype of ResponseException).
• Znojil\Comgate\Exception\ClientException: For HTTP client-side errors (4xx).
• Znojil\Comgate\Exception\ServerException: For HTTP server-side errors (5xx).
• Znojil\Comgate\Exception\ResponseException: For other unsuccessful HTTP responses.
• Znojil\Comgate\Exception\InvalidArgumentException: For invalid input (e.g. invalid credentials, missing required data).

use Znojil\Comgate\Exception\ApiException;
use Znojil\Comgate\Exception\ClientException;
use Znojil\Comgate\Exception\ServerException;

try{
	$result = $client->send(new CreateRequest($payment));
}catch(ApiException $e){
	echo $e->getMessage(); // error message from Comgate
	echo $e->getCode(); // error code from Comgate
}catch(ServerException $e){
	// Comgate server error (5xx)
}catch(ClientException $e){
	// HTTP client error (4xx)
}

All exceptions thrown by the library implement the Znojil\Comgate\Exception\Exception marker interface, so a single catch can cover them all.

📄 License

This library is open-source software licensed under the MIT license.