Installation

Installation

Seven steps, in order. Steps 4 and 5 are the ones most often skipped — without them refunds and saved cards fail at runtime rather than at install time.

Before you start, check the requirements: a Payplug account with your payment methods activated, a publicly reachable shop, and wkhtmltopdf if you want refunds.

---

1. Require the plugin

composer config extra.symfony.allow-contrib true
composer require payplug/sylius-payplug-plugin

2. Install the Flex recipe

composer recipes:install payplug/sylius-payplug-plugin --force

Registers the bundle, copies the configuration files, and — on Sylius 2.1+ — sets up the plugin's assets.

3. Run the migrations

bin/console doctrine:migrations:migrate

The plugin ships its own migrations: the saved-cards table, the refund history the back office reads, and the operation log used by Hosted Fields.

4. Declare Payplug as a refundable gateway

In config/services.yaml:

parameters:
    sylius_refund.supported_gateways:
        - payplug
        - payplug_oney
        - payplug_bancontact
        - payplug_apple_pay
        - payplug_american_express
        - payplug_scalapay
        - payplug_wero

List every gateway you plan to use. A gateway missing here produces payments the Refund Plugin will not refund through Payplug — and nothing warns you until a customer asks for their money back.

5. Apply the entity traits

The plugin ships no entity mappings of its own; it extends yours. All three traits are required.

App\Entity\Customer\Customer — the customer's saved cards:

<?php

declare(strict_types=1);

namespace App\Entity\Customer;

use Doctrine\ORM\Mapping as ORM;
use PayPlug\SyliusPayPlugPlugin\Entity\CardsOwnerInterface;
use PayPlug\SyliusPayPlugPlugin\Entity\Traits\CustomerTrait;
use Sylius\Component\Core\Model\Customer as BaseCustomer;

#[ORM\Entity]
#[ORM\Table(name: 'sylius_customer')]
class Customer extends BaseCustomer implements CardsOwnerInterface
{
    use CustomerTrait;
}

App\Entity\Payment\PaymentMethod — the gateway configuration, including the connection to your Payplug account:

<?php

declare(strict_types=1);

namespace App\Entity\Payment;

use Doctrine\ORM\Mapping as ORM;
use PayPlug\SyliusPayPlugPlugin\Entity\Traits\PaymentMethodTrait;
use Sylius\Component\Core\Model\PaymentMethod as BasePaymentMethod;
use Sylius\Component\Payment\Model\PaymentMethodTranslationInterface;

#[ORM\Entity]
#[ORM\Table(name: 'sylius_payment_method')]
class PaymentMethod extends BasePaymentMethod
{
    use PaymentMethodTrait;

    protected function createTranslation(): PaymentMethodTranslationInterface
    {
        return new PaymentMethodTranslation();
    }
}

App\Entity\Payment\Payment — the refund history:

<?php

declare(strict_types=1);

namespace App\Entity\Payment;

use Doctrine\ORM\Mapping as ORM;
use PayPlug\SyliusPayPlugPlugin\Entity\Traits\PaymentTrait;
use Sylius\Component\Core\Model\Payment as BasePayment;

#[ORM\Entity]
#[ORM\Table(name: 'sylius_payment')]
class Payment extends BasePayment
{
    use PaymentTrait;
}

6. Extract the translations

bin/console translation:extract en PayPlugSyliusPayPlugPlugin --dump-messages
bin/console translation:extract fr PayPlugSyliusPayPlugPlugin --dump-messages

The plugin ships English, French and Italian.

7. Clear the cache

bin/console cache:clear

You are ready to configure a payment method.

---

Webhooks

Payplug tells your shop when a payment or a refund changes state. A payment is not finished when the shopper comes back from Payplug — it is finished when that call arrives.

You normally configure nothing. The plugin sends the callback URL with each payment, pointing at Sylius's own per-payment-method notify route (/payment-methods/{code}).

The exception is Hosted Fields, which runs on Payplug's Unified API. Its notifications come from a receiver configured once per merchant in the Payplug Cockpit, and that receiver needs one fixed URL:

https://your-shop.example.com/payplug/v2/ipn

Ask your account manager to set it up if you enable Hosted Fields.

A third route, /payplug/ipn, still answers for merchants onboarded before the per-payment-method notify mechanism existed. New installations do not need it.

When a notification is lost

A deploy at the wrong moment, an outage, a shop briefly unreachable — and an order sits in new with the money taken. Reconcile against the Payplug API:

bin/console payplug:update-payment-state

Safe to run on a schedule.

Logging

The plugin logs to its own Monolog channel, payplug. To capture it in production, add a handler in config/packages/prod/monolog.yaml:

monolog:
    handlers:
        payplug:
            level: debug
            type: stream
            path: "%kernel.logs_dir%/%kernel.environment%.log"
            channels: [payplug]

---

Checklist

• composer require payplug/sylius-payplug-plugin and the Flex recipe installed
• Migrations run
• Every gateway you use listed in sylius_refund.supported_gateways
• All three entity traits applied — Customer, PaymentMethod, Payment
• Translations extracted, cache cleared
• Shop reachable from the internet over HTTPS
• /payplug/v2/ipn registered with Payplug, if you use Hosted Fields
• payplug Monolog channel captured in production