README

HiPay integration for Sylius 2.x: Hosted Fields checkout (Symfony UX Live Component + HiPay JS SDK), Sylius Payment Request pipeline, Order API built through configurable processors, signed webhooks (Symfony Webhook), and optional Refund Plugin integration.

Composer package: hipay/hipay-payments-sylius

Compatibility

Node.js 22.x (see .nvmrc) is required only to build Stimulus / Encore assets in the test application, not in your Sylius application itself.

Installation in a Sylius application

1. Install the package

composer require hipay/hipay-payments-sylius

2. Register the bundle

If not picked up automatically, add it to config/bundles.php:

<?php

return [
    // ...
    HiPay\SyliusHiPayPlugin\SyliusHiPayPlugin::class => ['all' => true],
];

3. Import the plugin configuration

Create config/packages/hipay_payment_plugin.yaml:

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

4. Import the routes

Create config/routes/hipay_payment_plugin.yaml:

sylius_hipay_plugin_webhook:
    path: /payment/hipay/notify
    controller: 'webhook.controller::handle'
    methods: ['POST']
    defaults:
        type: 'hipay'

Edit config/routes/sylius_resource.yaml and add prefix part:

sylius_hipay_resource_routes:
resource: "sylius.symfony.routing.loader.resource"
type: service
prefix: '/%sylius_admin.path_name%'

5. Run database migrations

The plugin ships Doctrine migrations for its own tables (hipay_account, hipay_transaction, hipay_saved_card, hipay_pending_notification):

php bin/console doctrine:migrations:migrate

The defaults (30s tick, 180s buffer, 50 rows per batch, 8 retries with exponential backoff) work out of the box. You may override them in your application by redefining the relevant plugin parameters — see docs/webhook-async-processing.md.

6. Install front-end assets

The plugin's Stimulus controllers (hipay-hosted-fields, hipay-multibanco) are shipped as an npm package located inside the Composer vendor directory.

Add the package to your application's package.json (Symfony Flex usually adds it automatically when you composer require the plugin):

{
    "dependencies": {
        "@hipay/hipay-payments-sylius": "file:vendor/hipay/hipay-payments-sylius/assets"
    }
}

Install JavaScript dependencies (only if you use Webpack Encore, not needed for Asset Mapper):

yarn install
# or: npm install

Enable the controllers in assets/controllers.json (Symfony Flex usually adds it automatically when you composer require the plugin):

{
    "controllers": {
        "@hipay/hipay-payments-sylius": {
            "hipay-hosted-fields": {
                "enabled": true,
                "fetch": "eager"
            },
            "hipay-multibanco": {
                "enabled": true,
                "fetch": "eager"
            }
        }
    }
}

Rebuild your front-end assets:

# Webpack Encore
yarn encore dev
# or: npm install

# or AssetMapper
php bin/console importmap:install

7. Generate the payment key

This key is used to encrypt sensitive data in database.

php bin/console sylius:payment:generate-key

8. Run the HiPay webhook worker

HiPay notifications are buffered in hipay_pending_notification and applied by a Symfony Scheduler worker. Run one instance per application environment (systemd unit, Supervisor, container, etc.):

php bin/console messenger:consume scheduler_hipay_notifications --time-limit=3600 --memory-limit=128M

9. Configure a HiPay gateway

In the Sylius admin panel:

1. In the left sidebar, go to HiPay → Accesses and create a new account with your HiPay API credentials (username, password, passphrase, public credentials, environment, debug mode).
2. Go to Configuration → Payment Methods → New and pick a HiPay gateway (e.g. HiPay Hosted Fields).
3. In the gateway configuration form, link the account you created in step 1 and choose a payment product.

The same account can be linked to several HiPay payment methods (cards, Apple Pay, Bancontact, iDEAL, Multibanco, MB Way, Oney, PayPal). Create additional accounts under HiPay → Accesses if you need to separate test from production credentials, or to use distinct merchant accounts per channel.

For architecture details and customization, start with docs/payment-workflow.md and docs/add-payment-product.md.

Documentation

Official HiPay documentation (notifications, transaction status, Hosted Fields) is linked from these pages where relevant.

Features

• Shop: hipay_hosted_fields gateway, Live Component hipay_hosted_fields, Stimulus hipay-hosted-fields, HiPay SDK loaded with SRI-aware Twig helpers.
• Payment Request: Messenger handlers (NewOrderRequest, TransactionInformationRequest), HTTP response provider for 3DS forwarding and post-payment redirects.
• Order request: PaymentOrderRequestBuilder + tagged processors per payment product (card pipeline included; extensible).
• Webhooks: HMAC-validated payloads, NotificationProcessor, mapping via HiPayStatus to Sylius state machine.
• Admin: HiPay Account CRUD, gateway configuration types, admin Live Component for payment method forms.
• Extensions: Dedicated Symfony event classes for checkout, synchronous API handling, and webhook lifecycle — see events.md.
• Refund Plugin: Automatic integration with sylius/refund-plugin — HiPay refund API called on RefundPaymentGenerated — see refund-plugin.md.

Supported payment products

Additional products can be added without modifying the plugin — see docs/add-payment-product.md.

Developing this repository

The Sylius test application used for development and CI lives under tests/TestApplication/.

Prerequisites

• Symfony CLI
• PHP 8.2+ (see .php-version if present)
• Node.js & Yarn (Node 22.x per .nvmrc)
• Docker (optional; used by .symfony.local.yaml for database services)

Verify your environment:

make check

Bootstrap

Copy environment files for the test application (e.g. from .env / .env.local examples) under tests/TestApplication/, then:

make install

This typically runs prerequisite checks, composer install, starts the Symfony server (and Docker services when configured), creates the database, runs migrations, loads fixtures, and builds front-end assets. See the Makefile for the exact sequence.

Useful commands:

make up          # Start Symfony server
make stop        # Stop Symfony server
make cc          # Clear Symfony cache
make clean       # Drop DB, stop server, remove vendor/ node_modules/ var/ (destructive)
make test.all    # ECS, PHPStan, PHPMD, PHPUnit, Behat, YAML/Twig/container linters

Individual test targets: make test.phpunit.unit, make test.phpunit.integration, make test.phpunit.functional, make test.behat, make test.phpstan, make test.ecs, etc.

Local HTTPS and webhooks

For HiPay server-to-server notifications during local development, you need a public HTTPS URL (e.g. a tunneling tool). Configure the tunnel and set any required tokens in your .env files for the test application.

For Xdebug, use your platform’s PHP extension packages and start PHP with XDEBUG_MODE=debug when needed (see Symfony and PHP documentation).

Source layout

src/
├── Client/                 # HiPay SDK client resolution per Account
├── Command/                # Payment Request bus commands
├── CommandHandler/         # New order, transaction info, state machine updates
├── CommandProvider/        # Maps gateway actions to Messenger commands
├── Entity/                 # Account, Transaction, SavedCard
├── Event/                  # Domain events (checkout, API, webhook)
├── EventListener/          # Admin menu, workflow decorators
├── EventSubscriber/        # Order lifecycle, webhook-driven behaviour
├── Factory/                # Saved cards, etc.
├── Fixture/                # Sample Account fixtures
├── Form/                   # Admin Account and gateway / product configuration
├── Logging/                # Dedicated HiPay log channel
├── Mailer/                 # Fraud suspicion notifications
├── Migrations/             # Doctrine migrations
├── OrderPay/Provider/      # PaymentRequest HTTP response (redirects)
├── Payment/                # HiPay status mapping, Sylius transitions
├── PaymentOrderRequest/    # Context factory, builders, processors
├── PaymentProduct/         # Product handlers + registry (card, extensible)
├── Processor/              # Cancel, manual capture, notification side effects
├── Provider/               # Account, transaction, payment request, products
├── RefundPlugin/           # Optional Sylius Refund Plugin integration
├── Resolver/               # Channel-based payment method filtering
├── ThreeDS/                # 3DS mode value object
├── Twig/                   # Live Components, HiPay Twig extension
├── Validator/              # Webhook HMAC validation
└── Webhook/                # Request parser, consumer, NotificationProcessor

Quality

The project uses ECS (coding standard), PHPStan, PHPMD, PHPUnit, and Behat. Run make test.all before opening a pull request.

License

Apache License — see LICENSE.