PHPackages                             ages/payment-gateway - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Payment Processing](/categories/payments)
4. /
5. ages/payment-gateway

ActiveLibrary[Payment Processing](/categories/payments)

ages/payment-gateway
====================

Unified payment gateway API for Comgate and GoPay

02PHP

Since Apr 29Pushed 1mo agoCompare

[ Source](https://github.com/A-g-e-s/payment-gateway)[ Packagist](https://packagist.org/packages/ages/payment-gateway)[ RSS](/packages/ages-payment-gateway/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependenciesVersions (1)Used By (0)

ages/payment-gateway
====================

[](#agespayment-gateway)

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

[](#požadavky)

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

Konfigurace (Nette DI / NEON)
-----------------------------

[](#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

[](#test--sandbox)

Brána`test: true`Comgatevolání jdou na produkci, transakce jsou označeny jako testovacíGoPaypřepne na `https://gw.sandbox.gopay.com/`---

Použití
-------

[](#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

[](#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

[](#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)

[](#stavy-platby-paymentstatus-enum)

HodnotaComgateGoPay`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

[](#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)

[](#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í
------------------

[](#struktury-odpovědí)

### `PaymentResult`

[](#paymentresult)

PropertyTypPopis`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`

[](#paymentstatusresult)

PropertyTypPopis`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`

[](#refundresult)

PropertyTyp`ok``bool``errorCode``string|null``errorMessage``string|null`### `StornoResult`

[](#stornoresult)

PropertyTypPopis`ok``bool``gatewayNotified``bool``false` u GoPay — brána nebyla informována`errorCode``string|null``errorMessage``string|null`---

Výjimky
-------

[](#výjimky)

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

TřídaKdy 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
------------

[](#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

```

###  Health Score

20

—

LowBetter than 13% of packages

Maintenance60

Regular maintenance activity

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity11

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/20422823?v=4)[Jiří Hovad](/maintainers/A-g-e-s)[@A-g-e-s](https://github.com/A-g-e-s)

---

Top Contributors

[![A-g-e-s](https://avatars.githubusercontent.com/u/20422823?v=4)](https://github.com/A-g-e-s "A-g-e-s (3 commits)")

### Embed Badge

![Health badge](/badges/ages-payment-gateway/health.svg)

```
[![Health](https://phpackages.com/badges/ages-payment-gateway/health.svg)](https://phpackages.com/packages/ages-payment-gateway)
```

###  Alternatives

[omnipay/coinbase

Coinbase driver for the Omnipay payment processing library

18570.2k1](/packages/omnipay-coinbase)[yenepay/php-sdk

YenePay SDK for PHP

112.7k](/packages/yenepay-php-sdk)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)