Sylius

The ICEPAY for Sylius plugin connects your Sylius store to ICEPAY and adds ICEPAY as a payment option during checkout.

This guide explains how to install the plugin, connect your ICEPAY merchant, configure the payment method, and test your checkout before going live.

Source code

Requirements

Before installing the plugin, make sure your project meets the following requirements:

• Sylius 1.13
• PHP 8.1 or higher
• Composer
• An ICEPAY Account with access to a merchant

Sylius compatibility

The current plugin package declares support for Sylius ~1.13.0. If your project uses a newer major or minor Sylius version, verify compatibility before installing the plugin.

Start in Test mode

New ICEPAY merchants start in Test mode. We recommend installing and testing the plugin in a test or staging environment before accepting real payments.

Install the plugin

The Sylius plugin is installed directly from the ICEPAY GitHub repository using Composer.

1. Add the ICEPAY repository

   Add the ICEPAY Sylius repository to the repositories section of your project’s composer.json:

   {
     "repositories": [
       {
         "type": "vcs",
         "url": "https://github.com/ICEPAY/ICEPAY-for-Sylius"
       }
     ]
   }

2. Install the plugin

   From the root directory of your Sylius project, run:

   composer require icepay/icepay-for-sylius:dev-master

3. Register the plugin

   Add the ICEPAY plugin to config/bundles.php:

   <?php
   
   return [
       // ...
       SyliusIcepayPlugin\SyliusIcepayPlugin::class => ['all' => true],
   ];

4. Clear the cache

   Clear the Symfony cache after registering the plugin:

   php bin/console cache:clear

Note

The plugin currently does not have a tagged release and is installed from the master branch using dev-master.

Configure ICEPAY

After installing the plugin, create an ICEPAY payment method in the Sylius Admin.

1. Open the payment methods

   Sign in to the Sylius Admin and go to Configuration → Payment methods.

2. Create a payment method

   Create a new payment method and select the ICEPAY gateway.

3. Enter your merchant credentials

   Enter the Merchant ID and Merchant Secret of the ICEPAY merchant you want to connect.

   You can find these credentials in the ICEPAY Portal by opening Merchants and selecting your merchant.

4. Assign the payment method

   Configure the payment method for the channels where you want ICEPAY to be available.

5. Save the payment method

   Save the configuration and verify that ICEPAY is available during checkout.

Keep your Merchant Secret secure

Your Merchant Secret is used to authenticate requests to ICEPAY. Do not share it publicly, commit it to source control, or include it in support requests.

Supported payment methods

The ICEPAY for Sylius plugin currently supports:

• iDEAL | Wero
• Cards
• Bancontact
• PayPal
• Online Überweisen
• EPS

The payment methods available to your customers also depend on the payment methods enabled for your ICEPAY merchant.

Enable refunds

If you want to process refunds through ICEPAY from Sylius, an additional plugin configuration must be imported.

Add the following import to config/packages/_sylius.yaml:

imports:
    # ...
    - { resource: "@SyliusIcepayPlugin/config/config.yml" }

Then clear the Symfony cache:

php bin/console cache:clear

Note

This configuration is only required when you want to process refunds through ICEPAY.

Test your integration

Before accepting real payments, place at least one order while your ICEPAY merchant is in Test mode.

1. Add a product to your cart

   Go through your Sylius storefront as a customer and add a product to the cart.

2. Proceed to checkout

   Complete the required customer and shipping information and select ICEPAY as the payment method.

3. Place the order

   Confirm the order and continue to the ICEPAY Payment Page.

4. Complete the test payment

   In Test mode, select the payment result you want to simulate.

5. Check the Sylius order

   Open the corresponding order in the Sylius Admin and verify that the payment and order statuses have been updated correctly.

6. Check the payment in the ICEPAY Portal

   Open the corresponding test payment in the ICEPAY Portal and verify that its status matches the payment in Sylius.

Test different payment outcomes

We recommend testing more than a successful payment. Verify that your store also handles cancelled and unsuccessful payments correctly.

How payments work

Once the plugin is installed and configured, the payment flow is handled automatically.

1. The customer places an order

   The customer selects ICEPAY during the Sylius checkout and confirms the order.

2. The payment is created

   The plugin creates the payment with ICEPAY using the Sylius order information.

3. The customer completes the payment

   The customer is redirected to the ICEPAY Payment Page to complete the payment.

4. The plugin updates the order and the customer can return

   The plugin processes the payment update and updates the Sylius payment and order state. The customer can also return to your Sylius store after the payment flow.

You do not need to build the ICEPAY payment creation and redirect flow yourself when using the Sylius plugin.

Payment updates and customer redirects happen independently and can arrive in either order. Use the server-side payment update to determine the payment result.

Refund a payment

If refund support has been enabled using the additional configuration described above, payments can be refunded through the ICEPAY integration.

1. Open the order

   Open the corresponding order in the Sylius Admin.

2. Locate the payment

   Find the ICEPAY payment associated with the order.

3. Initiate the refund

   Use the available refund action to submit the refund through ICEPAY.

4. Verify the result

   Check the payment in both Sylius and the ICEPAY Portal to confirm that the refund was processed successfully.

The ICEPAY Sylius plugin supports refunds when the refund configuration has been imported.

Go live

Once you’ve successfully tested the integration, you can prepare your store for real payments.

1. Verify your checkout

   Make sure ICEPAY appears correctly during checkout and your test orders receive the expected payment and order statuses.

2. Submit your merchant for approval

   Your ICEPAY merchant must be approved before it can process real payments.

3. Switch your merchant to Live mode

   Once approved, change the merchant from Test mode to Live mode in the ICEPAY Portal.

4. Place a final order

   We recommend placing a small live order to verify the complete payment flow.

Learn more about going live

Prepare to process live payments.

Update the plugin

Because the plugin is currently installed from the master branch, test updates carefully before deploying them to production.

Update the ICEPAY plugin using Composer:

composer update icepay/icepay-for-sylius
php bin/console cache:clear

After updating, verify that:

• the ICEPAY bundle is still registered;
• your payment method configuration is still available;
• the payment method appears during checkout;
• test payments update the corresponding Sylius payment correctly;
• refunds still work if refund support is enabled.

Tip

Test plugin updates in a staging environment before deploying them to production.

Troubleshooting

ICEPAY is not visible during checkout

Check that:

• The ICEPAY package is installed.
• SyliusIcepayPlugin\SyliusIcepayPlugin is registered in config/bundles.php.
• The ICEPAY payment method is enabled in Configuration → Payment methods.
• The payment method is assigned to the correct Sylius channel.
• The correct ICEPAY merchant credentials are configured.
• Your Sylius and PHP versions meet the plugin requirements.

Clear the Symfony cache after changing the configuration:

php bin/console cache:clear

If ICEPAY still does not appear, check your Symfony logs for related errors.

The plugin does not load after installation

Confirm that Composer installed the plugin successfully:

composer show icepay/icepay-for-sylius

Make sure the bundle is registered in config/bundles.php:

SyliusIcepayPlugin\SyliusIcepayPlugin::class => ['all' => true],

Then clear the Symfony cache:

php bin/console cache:clear

If the application still cannot load the plugin, check the Symfony logs and confirm that your PHP and Sylius versions satisfy the plugin’s Composer requirements.

The payment remains pending

Open the corresponding order in the Sylius Admin and check its payment state.

Then open the payment in the ICEPAY Portal and compare its status with the Sylius payment.

If the payment has been completed in ICEPAY but the Sylius payment has not been updated, check your Symfony logs for errors related to the payment callback or status processing.

If the issue continues, contact the ICEPAY team with the order number, payment reference, Merchant ID, and approximate time of the payment.

Do not include your Merchant Secret in a support request.

The customer cannot complete the payment

Confirm that:

• The correct Merchant ID and Merchant Secret are configured.
• The ICEPAY merchant is enabled.
• The required payment method is enabled for the merchant.
• Your Sylius application can communicate with ICEPAY.
• Your application is accessible using its configured public URL.

Check the Symfony logs for errors generated while creating or processing the payment.

If an error is shown during checkout, include the error message when contacting the ICEPAY team.

The payment status in Sylius differs from the ICEPAY Portal

Open the Sylius order and review the associated payment state.

Use the payment details and server-side payment status in the ICEPAY Portal when investigating the payment.

If the statuses remain different, check your application logs for errors while processing the ICEPAY payment result.

Contact the ICEPAY team with the Sylius order number, payment reference, Merchant ID, and approximate time of the payment if the issue continues.

Refunds are not available

Make sure the ICEPAY refund configuration has been imported in config/packages/_sylius.yaml:

imports:
    # ...
    - { resource: "@SyliusIcepayPlugin/config/config.yml" }

Clear the Symfony cache after adding the configuration:

php bin/console cache:clear

Also confirm that the original payment is eligible for a refund.

If the refund still cannot be processed, check the Symfony logs and contact the ICEPAY team with the order number, payment reference, Merchant ID, and any relevant error message.

The plugin does not work after an update

Confirm that your PHP, Sylius, and ICEPAY plugin versions are compatible.

Check that the plugin is still installed:

composer show icepay/icepay-for-sylius

Confirm that the bundle is still registered in config/bundles.php, then clear the Symfony cache:

php bin/console cache:clear

Verify your ICEPAY payment method configuration and test the checkout again.

If the issue continues, contact the ICEPAY team with the plugin version, Sylius version, PHP version, and any relevant error message.