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.