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);

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\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)
}

📄 License

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