ages/payment-gateway

There is no license information available for the latest version (dev-main) of this package.

Unified payment gateway API for Comgate and GoPay

dev-main 2026-04-29 16:35 UTC

Requires

• php: >=8.4
• contributte/comgate: ^0.5.1
• gopay/payments-sdk-php: ^1.11

Requires (Dev)

• phpstan/phpstan: ^2.0

Unknown License

README

Jednotné API pro platební brány Comgate a GoPay. Obě integrace sdílejí stejné entity a rozhraní — přepnutí brány nevyžaduje změnu aplikačního kódu.

Požadavky

• PHP 8.4+
• gopay/payments-sdk-php ^1.11
• contributte/comgate ^0.5.1

Konfigurace (Nette DI / NEON)

services:
    comgateConfig: Ages\PaymentGateway\Config\ComgateConfig(
        merchant: 'merchant-id'
        secret:   'merchant-secret'
        test:     false
        # gatewayUrl: https://payments.comgate.cz/v1.0/    # výchozí hodnota
    )

    goPayConfig: Ages\PaymentGateway\Config\GoPayConfig(
        clientId:        'my-client-id'
        clientSecret:    'my-client-secret'
        goid:            'goPay-id'
        returnUrl:       'https://shop.cz/payment/return'
        notificationUrl: 'https://shop.cz/payment/notify'
        test:            false
        # scope:    payment-all    # výchozí hodnota
        # language: CS             # výchozí hodnota
        # timeout:  30             # výchozí hodnota
    )

    - Ages\PaymentGateway\PaymentGateway

Obě konfigurace jsou volitelné — shop používající pouze Comgate vynechá goPayConfig a naopak. PaymentGateway autowire dle přítomných typů v kontejneru.

Test / sandbox

Brána	test: true
Comgate	volání jdou na produkci, transakce jsou označeny jako testovací
GoPay	přepne na https://gw.sandbox.gopay.com/

Použití

Brána se vybírá pomocí enum Gateway a metody gateway():

use Ages\PaymentGateway\Entity\Enum\Gateway;

$this->paymentGateway->gateway(Gateway::Comgate)->createPayment($payment);
$this->paymentGateway->gateway(Gateway::GoPay)->createPayment($payment);

Pokud brána není nakonfigurována, metoda hodí GatewayInitializationException.

Vytvoření platby

use Ages\PaymentGateway\Entity\CreatePayment;
use Ages\PaymentGateway\Entity\Enum\Gateway;
use Brick\Money\Money;

$payment = CreatePayment::of(
    money:    Money::of($order->priceTax, $order->currency->iso),
    label:    sprintf('Objednávka %s', $order->code),
    refId:    $order->code,
    email:    $order->email,
    fullName: $order->invoiceFullName,
);

$res = $this->paymentGateway->gateway(Gateway::Comgate)->createPayment($payment);

if (!$res->ok) {
    // $res->errorCode, $res->errorMessage
    return null;
}

$order->transactionId  = $res->transactionId;
$order->transactionUrl = $res->redirectUrl;   // URL pro přesměrování zákazníka

Stav platby

use Ages\PaymentGateway\Entity\Enum\Gateway;

$res = $this->paymentGateway->gateway(Gateway::Comgate)->paymentStatus($order->transactionId);

if (!$res->ok) {
    // chyba komunikace s bránou
}

echo $res->status->value;     // PAID, PENDING, CANCELLED, ...
echo $res->amountInCents;     // částka v haléřích
echo $res->currency;          // CZK
echo $res->refId;             // číslo objednávky

Stavy platby (PaymentStatus enum)

Hodnota	Comgate	GoPay
Pending	PENDING	CREATED, PAYMENT_METHOD_CHOSEN
Paid	PAID	PAID
Authorized	AUTHORIZED	AUTHORIZED
Cancelled	CANCELLED	CANCELED
Refunded	—	REFUNDED
PartiallyRefunded	—	PARTIALLY_REFUNDED
TimedOut	—	TIMEOUTED
Unknown	ostatní	ostatní

Refundace

use Ages\PaymentGateway\Entity\Enum\Gateway;
use Brick\Money\Money;

$res = $this->paymentGateway->gateway(Gateway::Comgate)->refundPayment(
    transactionId: $order->transactionId,
    amount:        Money::of('150.00', 'CZK'),
);

if (!$res->ok) {
    // $res->errorCode, $res->errorMessage
}

Storno (zrušení čekající platby)

use Ages\PaymentGateway\Entity\Enum\Gateway;

$res = $this->paymentGateway->gateway(Gateway::Comgate)->stornoPayment($order->transactionId);

if (!$res->ok) {
    // chyba na straně brány
}

Pozor — GoPay: stornoPayment u GoPay nevolá žádné API (GoPay zrušení čekající platby nepodporuje). Platební odkaz zůstane aktivní, dokud nevyprší. $res->ok bude true, ale $res->gatewayNotified bude false.

Doporučené ošetření v notification handleru:

if ($order->isCancelled() && $status->status === PaymentStatus::Paid) {
    // zákazník zaplatil za zrušenou objednávku → řeš přes účetnictví
}

Struktury odpovědí

PaymentResult

Property	Typ	Popis
ok	bool	true = úspěch
transactionId	string|null	ID transakce z brány
redirectUrl	string|null	URL pro přesměrování zákazníka
errorCode	string|null	kód chyby (jen při ok = false)
errorMessage	string|null	popis chyby (jen při ok = false)

PaymentStatusResult

Property	Typ	Popis
ok	bool
status	PaymentStatus|null	normalizovaný stav
transactionId	string|null
refId	string|null	číslo objednávky
amountInCents	int|null	částka v haléřích
currency	string|null	ISO 4217 (CZK, EUR, …)
errorCode	string|null
errorMessage	string|null

RefundResult

Property	Typ
ok	bool
errorCode	string|null
errorMessage	string|null

StornoResult

Property	Typ	Popis
ok	bool
gatewayNotified	bool	false u GoPay — brána nebyla informována
errorCode	string|null
errorMessage	string|null

Výjimky

Všechny výjimky rozšiřují Ages\PaymentGateway\Exception\PaymentGatewayException.

Třída	Kdy nastane
GatewayInitializationException	Nepodaří se sestavit klienta brány
InvalidGatewayResponseException	Brána vrátí neočekávaný formát odpovědi

| GatewayInitializationException je hozena i v případě, kdy zavoláte gateway() pro bránu, která nebyla nakonfigurována.

use Ages\PaymentGateway\Entity\Enum\Gateway;
use Ages\PaymentGateway\Exception\PaymentGatewayException;

try {
    $res = $this->paymentGateway->gateway(Gateway::Comgate)->createPayment($payment);
} catch (PaymentGatewayException $e) {
    // infrastrukturní chyba (síť, neočekávaný formát, nekonfigurovaná brána, …)
    // chyba obchodní logiky (zamítnutá platba) je v $res->ok = false
}

Architektura

src/
├── Config/
│   ├── ComgateConfig.php         konfigurace Comgate
│   ├── GoPayConfig.php           konfigurace GoPay
│   └── GatewayConfig.php         volitelný wrapper obou konfigurací
├── Entity/
│   ├── Enum/
│   │   ├── Gateway.php           výběr brány (Comgate, GoPay)
│   │   └── PaymentStatus.php     normalizované stavy obou bran
│   ├── CreatePayment.php         vstupní entita pro vytvoření platby
│   ├── PaymentResult.php
│   ├── PaymentStatusResult.php
│   ├── RefundResult.php
│   └── StornoResult.php
├── Exception/
│   ├── PaymentGatewayException.php
│   ├── GatewayInitializationException.php
│   └── InvalidGatewayResponseException.php
├── Gateway/
│   ├── GatewayInterface.php      createPayment, paymentStatus, refundPayment, stornoPayment
│   ├── ComgateGateway.php
│   └── GoPayGateway.php
└── PaymentGateway.php            DI entry point — gateway(Gateway) vrátí GatewayInterface