unicorncrew-tech / sylius-comgate-plugin

v1.0.2 2026-09-14 20:01 UTC

Requires

• php: ^8.2
• comgate/sdk: ^1.7
• payum/core: ^1.7
• sylius/sylius: ^2.0
• symfony/config: ^6.4 || ^7.0
• symfony/dependency-injection: ^6.4 || ^7.0
• symfony/form: ^6.4 || ^7.0
• symfony/http-foundation: ^6.4 || ^7.0
• symfony/http-kernel: ^6.4 || ^7.0
• webmozart/assert: ^1.11

Requires (Dev)

• nyholm/psr7: ^1.8
• phpstan/extension-installer: ^1.0
• phpstan/phpstan: ^1.11
• phpstan/phpstan-strict-rules: ^1.5
• phpstan/phpstan-webmozart-assert: ^1.0
• phpunit/phpunit: ^10.5
• sylius-labs/coding-standard: ^4.0
• sylius/test-application: ^2.0.0@alpha
• symfony/phpunit-bridge: ^7.4
• symfony/var-exporter: ^7.4

MIT

• Unicorncrew

• payment
• sylius
• payum
• comgate
• sylius-plugin

Published on Packagist.org on 2026-09-14 20:01 UTC

README

Sylius Comgate Plugin

Integration of the Czech payment gateway Comgate with Sylius as a Payum gateway.

Requirements

• Sylius ^2.0
• PHP ^8.2
• A Comgate merchant account (comgate.cz), with the merchant ID and secret from portal.comgate.cz.

How it works

Comgate is a redirect + server-to-server-webhook gateway: the shopper is redirected to a Comgate-hosted payment page, Comgate then confirms the outcome by calling back a STATUS URL on your shop and by redirecting the shopper back to a PAID/CANCELLED/PENDING URL.

This plugin implements that flow as a Payum gateway (factory name comgate), the same architecture used by the official sylius/paypal-plugin and sylius/mollie-plugin:

• CaptureAction creates the payment at Comgate and throws a redirect to the hosted payment page. When the shopper is redirected back, it re-fetches the authoritative status straight from Comgate rather than trusting query parameters set by the browser.
• NotifyAction handles the asynchronous webhook Comgate calls on payum_notify_do_unsafe/{gateway}. It only uses the webhook payload to look the payment up (by refId/transId), the payment status itself is always re-fetched through Client::getStatus().
• StatusAction maps the Comgate payment status onto Sylius' payment state machine. Sylius' own UpdatePaymentStateExtension (registered core-wide) takes care of applying the corresponding transition after every Capture/Notify call, so no extra listener is required.

Installation

1. Require the plugin:

   composer require unicorncrew-tech/sylius-comgate-plugin

2. Enable it in config/bundles.php:

   return [
       // ...
       Unicorncrew\SyliusComgatePlugin\UnicorncrewSyliusComgatePlugin::class => ['all' => true],
   ];

3. Import its configuration in config/packages/unicorncrew_sylius_comgate.yaml:

   imports:
       - { resource: "@UnicorncrewSyliusComgatePlugin/config/config.yaml" }

4. Run migrations if needed (this plugin adds no new entities/tables, so this is normally a no-op) and clear the cache.

Configuration

1. Go to the admin panel, Configuration > Payment methods, and create a new payment method.
2. Pick Comgate as the gateway.
3. Fill in:
   • Code: e.g. comgate — this becomes the gateway name used in the webhook URL below.
   • Channels: the channels this payment method should be available on.
   • Merchant ID / Secret: from portal.comgate.cz.
   • Test mode: check this while testing; Comgate flags the payment as a test transaction rather than using a different endpoint.
4. Give it a display name for each locale, and save.

Webhook (STATUS URL)

In portal.comgate.cz, set the STATUS URL (and, if you want Comgate itself to redirect back with a PAID/CANCELLED/PENDING query string, the corresponding redirect URLs — this plugin already sets its own dynamic return URL per payment, so those portal-level URLs are only a fallback) to:

https://your-shop.example/payment/notify/unsafe/<payment method code>

Use bin/console debug:router payum_notify_do_unsafe to double check the exact path prefix used by your shop, and the payment method's code (as configured in step 3 above) as the <payment method code> segment.

Testing

This plugin uses sylius/test-application as a dev dependency instead of bundling its own throwaway Sylius app. tests/Unit runs in isolation (no framework needed); tests/Functional boots the real Sylius kernel — with this plugin enabled via tests/TestApplication/bundles.php and tests/TestApplication/.env — and asserts the container actually compiles: the comgate Payum gateway factory is registered, its actions resolve, and the admin gateway configuration form type is wired, i.e. everything bin/console debug:container would otherwise be used for.

composer install

# Full test suite (unit + functional). Compiling the real Sylius container needs more than the
# default CLI 128M memory_limit.
php -d memory_limit=-1 vendor/bin/phpunit

vendor/bin/phpstan analyse -c phpstan.neon.dist
vendor/bin/ecs check src/ tests/

No database is required to run the suite (tests/TestApplication/.env points DATABASE_URL at a local SQLite file); it's only needed for Behat/browser-level testing, which this plugin does not ship.

Releasing

Commit messages MUST follow Conventional Commits - this is what drives versioning and the changelog:

• feat: … - new functionality, bumps the minor version (1.2.0 -> 1.3.0).
• fix: … - bug fixes, bumps the patch version (1.2.0 -> 1.2.1).
• feat!: … / a BREAKING CHANGE: footer - bumps the major version (1.2.0 -> 2.0.0).
• chore:, docs:, test:, ci:, refactor:, style: - no release on their own; grouped in the changelog instead of triggering a version bump.

Releases are automated with release-please: every push to master runs .github/workflows/release-please.yaml, which keeps a "Release PR" up to date with the next version (computed from the commits above) and the generated CHANGELOG.md. Merging that PR tags the release and publishes a GitHub Release; Packagist picks up new tags automatically once the repository is registered there.

There is no version field to bump in composer.json - Packagist and Composer resolve versions from git tags, so nothing else needs to change by hand.

Security

If you think you have found a security issue, please do not use the public issue tracker; contact the maintainers directly instead.

License

This plugin is released under the MIT License.