Enhanced Scheme Data (ESD)

What is ESD?

Enhanced Scheme Data (ESD) refers to industry-specific metadata sent to card schemes (like Visa or Mastercard) to improve:

• Interchange rates (reduced processing fees),

• Fraud detection through better context,

• Authorization performance.

ESD is especially beneficial for US-based card transactions in sectors like car rental, travel, or digital goods.

Official documentation: Adyen – Enhanced Scheme Data

Prerequisites

ESD data is only collected and included in the payment request when all of the following conditions are met:

1. ESD is enabled in the Adyen payment method configuration.

2. The currency of the order is supported (USD by default).

3. The billing country is supported (US by default).

4. The card brand is supported (visa and mc by default).

5. The payment method type is scheme (i.e., credit/debit card).

These conditions help prevent ESD from being sent where it is not applicable or supported.

Beware that ESD support is only available when using the automatic capture mode within a payment method. For more information about capture modes, check the Payment Capture Modes page.

Configuration Options

You can configure where and when ESD is applied by setting:

# config/packages/sylius_adyen.yaml

sylius_adyen:
    esd:
        supported_currencies: 
            - 'USD'
        supported_countries:
            - 'US'
        supported_card_brands:
            - 'visa'
            - 'mc'

Key	Description	Default
supported_currencies	Currency codes eligible for ESD (e.g., USD)	['USD']
supported_countries	ISO 3166-1 alpha-2 country codes (e.g., US)	['US']
supported_card_brands	Lowercase card brand keys (e.g., visa, mc, amex)	['visa', 'mc']

How ESD level is determined?

The plugin automatically determines which ESD type (also referred to as “level”) should be used for a given payment request:

1. Manual override: If an ESD type is explicitly selected in the admin panel, it takes precedence.

2. MCC analysis: If no type is selected, the plugin checks the Merchant Category Code and matches it to the correct collector.

3. Default fallback: If nothing matches, Level 3 ESD is applied as the most comprehensive fallback.

Admin Panel Configuration

In Sylius Admin Panel, you can configure ESD per Adyen payment method:

Field	Description
Enable Enhanced Scheme Data (esdEnabled)	Checkbox to toggle ESD support.
ESD Type (esdType)	Dropdown with available ESD types (e.g., Level 2, Level 3). 💡 "Select the appropriate Enhanced Scheme Data type for your business." Options come from registered ESD collectors.
Merchant Category Code (merchantCategoryCode)	4-digit MCC used for automatic ESD detection when no type is selected. 💡 "Your 4-digit MCC code to automatically determine ESD type."

These settings give merchants control over when and how ESD is applied.

Commodity Codes for Product Variants

To further improve interchange rates, commodity codes can be configured for each product variant.

How to configure?

1. Go to Products → Manage variants -> List variants -> Edit.

2. Locate the "Commodity Code" field.

3. Enter a valid 12-digit code.

4. Now the code will be included in the payload and the product will be categorized more precisely.

Adding New ESD Types

The plugin supports creating custom ESD types using a tag-based, auto-discovered collector system.

• Implement EsdCollectorInterface

• Tag the service using sylius_adyen.esd.collector

• Optionally define priority and a friendly name (for admin UI)

📚 View Cookbook: Adding a New ESD Type