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.

---

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 — see Webhooks and logging

Next: Configuration.