How to add a new Enhanced Scheme Data (ESD) type to the Adyen Plugin?

This guide walks you through adding a brand‑new ESD type to the Adyen plugin in a Sylius project. We’ll build a Car Rental ESD as a concrete example, but the pattern applies to any new ESD type.

Prerequisites

• A working Sylius application.

• Adyen plugin installed and configured in your project.

• Familiarity with the business data you want to ship in ESD (field names, formats, and when it should apply, typically decided by Merchant Category Code).

Tip: ESD is optional metadata sent to card schemes to improve interchange rates and fraud signals. Your payload shape must match what your schemes expect.

How the ESD system works?

• EsdCollectorInterface - contract every ESD type implements.

interface EsdCollectorInterface
{
    public function supports(string $merchantCategoryCode): bool;
    public function collect(OrderInterface $order): array;
}

• CompositeEsdCollector - asks all collectors which one supports the current MCC and delegates collection to the proper one.

• EsdTypeProvider - exposes available ESD types to forms.

• ClientPayloadFactory - merges ESD data into the outgoing payment payload.

• DI Tagging: Each collector is registered with sylius_adyen.esd.collector.

• Auto‑discovery: The provider and composite collector discover collectors via tags; forms show available types automatically.

Design your new ESD type

Before coding, decide:

1. When does it apply? Usually via MCCs (e.g., car rental MCCs 3351-3500 range; use the ones your acquirer requires).

2. Which fields are required? Define a typed, minimal payload that your downstream expects.

Step 1: Implement the Collector

Create a class that implements EsdCollectorInterface. Put it in your app namespace (e.g., App\Collector).

<?php

declare(strict_types=1);

namespace App\Collector;

use Sylius\Component\Core\Model\OrderInterface;
use Sylius\Component\Order\Model\AdjustmentInterface;

final class CarRentalEsdCollector implements EsdCollectorInterface
{
    /** @var string[] */
    private array $supportedMccs = [
        // Fill with your MCCs. Example (placeholder):
        '3351', '3352', '3353', // ...
    ];

    public function supports(string $merchantCategoryCode): bool
    {
        return \in_array($merchantCategoryCode, $this->supportedMccs, true);
    }

    public function collect(OrderInterface $order): array
    {
        return [
            // Map data from the Order to ESD fields and return them as an array
        ];
    }
}

Step 2: Register the service (with tag)

Add the service definition with the collector tag in config/services.xml:

<!-- config/services.xml -->
<service id="app.collector.esd.car_rental" class="App\Collector\CarRentalEsdCollector">
    <!-- 
      priority: higher number wins when multiple collectors support the same MCC
      type: the human‑friendly key shown by forms/translation
    -->
    <tag name="sylius_adyen.esd.collector" priority="200" type="car_rental" />
</service>

Notes:

• priority: If two collectors claim the same MCC, the higher priority takes precedence.

• type: This is used by EsdTypeProvider and your translations to show a readable option in admin.

Step 3: Add a translation key

Expose a friendly name for admin forms. For example, in translations/messages.en.yaml:

sylius_adyen:
    ui:
        esd_type_car_rental: "Car Rental Data"

Step 4: Wire it into admin configuration

With the service tagged, the plugin’s forms automatically list your new ESD type. In Admin → Payment Methods → [Your Adyen method], you can:

• Force a specific ESD type: pick "Car Rental Data" from the dropdown to always include this ESD.

• Use MCC detection: leave the dropdown unset and provide an MCC; the CompositeEsdCollector chooses the matching collector at runtime.

This is handy for multi‑brand setups where different stores or sales channels use different MCCs.

You’re done, your new ESD type is now discoverable by forms, automatically selected by MCC, and included in the Adyen payload via the ClientPayloadFactory.