Payment-method icon

Level 2/3 data

Include level 2/3 data in your requests for US payments with Mastercard and Visa.

Level 2/3 enhanced scheme data (ESD) helps you track the amount spent on corporate cards and the amount of sales tax. If you are eligible to send level 2/3 data, you can send it in your requests to Adyen to benefit from lower interchange rates for Mastercard and Visa transactions.

For American Express, you receive no financial incentive, but you can include the data for fraud prevention and reporting purposes.

  • Level 2 data is purchase and tax details for the payment.
  • Level 3 data is the combination of level 2 data and line item details such as product quantities and descriptions.

Requirements

In addition to the requirements that apply to sending ESD, take into account the following additional limitations for sending level 2/3 data.

Requirement Description
Limitations
  • Starting on April 1, 2026:
    • Visa supports level 3 data only.
    • Mastercard supports both level 2 and level 3 data.
  • You can only send level 2/3 data for business cards, purchasing cards, and corporate cards. For most business cards, you can only send level 2 data.
  • The minimum total tax amount for a transaction that you send level 2 data for must be 0.1%. This does not apply to level 3 data.
  • The maximum total tax amount for a transaction that you send level 2/3 data for can be:
    • 30% for Mastercard
    • 22% for Visa

How it works

If you are eligible to send level 2/3 data, you include the data in your payment or capture requests to Adyen. Optionally, you can receive information in your standard webhooks about the status of the level 2/3 data you submitted in your payment requests. You receive this information as additionalData included in the webhook message.

  1. Review the data validation guidelines before building your implementation to send level 2/3 data.
  2. If you want to receive information about the data you submitted, enable receiving level 2/3 data insights in webhook messages.
  3. Send level 2/3 data in your payment or capture request for a transaction. The request you send it in depends on your capture setting:
  4. After the payment has been captured, monitor the status of your level 2/3 data using the information in the webhook message that you receive.
  5. If the level 2/3 data you submitted does not meet the data requirements, the webhook message includes the reason. Use this information to change the data you send in following requests, so that it correctly meets requirements.

Level 2/3 data validation

The level 2/3 data you send in your requests must meet the following requirements:

If the data that you send does not meet requirements, Adyen does the following:

  • If a required field is missing or incorrectly formatted for both levels, we drop all level 2/3 data. You do not qualify for the lower interchange rates until you fix and resend the request.
  • If your request contains errors only for level 3 data, or the card used in the transaction is only eligible for type 2 data, we drop the level 3 data and only submit the level 2 data.
  • If an optional field is incorrectly formatted, we drop the optional fields and submit only the required data fields.

Amount calculations

For Visa, the amount values that you provide in your request must reflect discount amounts, shipping amounts, and local tax amounts:

  • Line item total must accurately reflect the quantity, unit price, and the discount(s) applied.
    • Calculation example: itemDetailLines.totalAmount = (itemDetailLines.quantity x itemDetailLines.unitPrice) - itemDetailLines.discountAmount
  • The total amount in the capture request must accurately reflect all costs related to a purchase, such as the sum of line item totals, any shipping costs, and local taxes.
    • Always send level 2/3 data in the capture request if the total amount in payment and capture request are different.
    • Calculation example: amount.value = the sum of each itemDetailLines.totalAmount + freightAmount + totalTaxAmount

Enable receiving level 2/3 data insights in webhook messages

Update your webhook configuration to start receiving the information in webhook messages with eventcode: AUTHORISATION and eventCode: CAPTURE.

  1. In your Customer Area, go to Developers >  Webhooks.
  2. From the list of webhooks, select the one to configure.
  3. Select the edit icon.
  4. Under Additional Settings, select Include ESD Validation Result.
  5. Select Save configuration.
  6. If you use automatic capture or send the L2/3 data in the payment request, ask our Support Team to enable receiving information about level 2/3 data in webhook messages with eventCode: AUTHORISATION.

After you enable the feature, the additionalData field in your webhook messages contains the following information about the data validation:

Field Description
enhancedSchemeDataReceived Indicates the type of data that we received from you. Possible values:
  • L2
  • L3
  • null
enhancedSchemeDataSubmitted Indicates the type of data that we submitted to Mastercard and Visa after data validation. Possible values:
  • L2
  • L3
  • null
enhancedSchemeDataRefusalReasons If a required field is invalid or missing, and we drop all level 2/3 data, this informs you about the invalid or wrong data that caused the error.
enhancedSchemeDataWarningReasons If we drop optional level 2/3 data fields you submitted or we only submit the level 2 data, this informs you about the reason.

Send level 2/3 data

  1. Include level 2/3 data in the enhancedSchemeData.levelTwoThree object in your payment or capture request.

    The object has the same fields in each request. The following table shows which fields are required and optional.

    Level Field Required Description Value
    2 and 3 enhancedSchemeData.levelTwoThree.customerReferenceNumber
    String    		 Required The reference number that identifies the customer and their order. Format:
    • ASCII
    • Maximum 25 characters
    • Must not start with a space, or contain only spaces or zeros
    2 and 3 levelTwoThree.totalTaxAmount
    Integer    		 Required The amount of state or provincial tax included in the total transaction amount.

    For level 2 data, the value must not be zero. For level 3 data, the value can be zero.    		 Format:

    Example: 2000 means USD 20.00.
    3 levelTwoThree.itemDetailLines.productCode
    String    		 Required Your unique code for the item or service. You can use your own code or the product code from the manufacturer. Format:
    • ASCII
    • Maximum 12 characters
    3 levelTwoThree.itemDetailLines.description
    String    		 Required A description of the item that gives details about the purchase.

    For Visa transactions with level 3 data, the description must not resemble your merchant name, and must not consist only of common words such as product or service.    		 Format:
    • ASCII
    • Maximum 26 characters
    • Must not be a single character, blank, or only special characters
    • Must not start with a space, or contain only spaces or zeros
    3 levelTwoThree.itemDetailLines.quantity
    Integer    		 Required The number of items. The value must be greater than zero. Format:
    • Numeric
    • Maximum: 9999
    3 levelTwoThree.itemDetailLines.unitOfMeasure
    String    		 Required The unit of measurement for the item. Format:
    • ASCII
    • Maximum 3 characters
    3 levelTwoThree.itemDetailLines.commodityCode
    String    		 Required The code that identifies the item in a standardized commodity coding scheme, such as UNSPSC, HS, NAICS, or NAPCS. Format:
    • ASCII
    • Maximum 12 characters
    • Must not start with a space, or contain only spaces or zeros
    3 levelTwoThree.itemDetailLines.totalAmount
    Integer    		 Required The total amount for the line item. Format:
    3 levelTwoThree.itemDetailLines.unitPrice
    Integer    		 Required The price per unit. Format:
    3 levelTwoThree.destination.countryCode
    String    		 Conditionally required
    See conditions    		 The country code of the destination address. Format:
    • ASCII
    • Two-letter ISO 3166-1 alpha-2 or three-letter alpha-3 code
    3 levelTwoThree.destination.postalCode
    String    		 Conditionally required
    See conditions    		 The postal code of the destination address. Format:
    • ASCII
    • Maximum 10 characters
    • Must not start with a space
    • For the US, five or nine digits, for example 10001 or 10001-0000
    • For Canada, six characters, for example M4B 1G5
    3 levelTwoThree.destination.stateOrProvince
    String    		 Conditionally required
    See conditions    		 The state or province code of the destination address. Format:
    • ASCII
    • Maximum 3 characters
    • Must not start with a space
    3 levelTwoThree.shipFromPostalCode
    String    		 Conditionally required
    See conditions    		 The postal code of the address that the item ships from. Format:
    • ASCII
    • Maximum 10 characters
    • For the US, five or nine digits, for example 10001 or 10001-0000
    • For Canada, six characters, for example M4B 1G5
    3 levelTwoThree.dutyAmount
    Integer    		 The duty tax amount. Format:
    3 levelTwoThree.freightAmount
    Integer    		 The shipping amount. Format:
    3 levelTwoThree.orderDate
    String    		 The date of the order. Format: ISO 8601 date: yyyy-MM-dd
    3 levelTwoThree.itemDetailLines.discountAmount
    Integer    		 The discount amount. Format:

    Additional required information

    You must send additional information in additional parameters when all the following conditions are met:

    • The transaction involves a corporate card.
    • The transaction is acquired in the US.
    • The transaction involves shipping physical goods.

    Select the endpoint for the corresponding request example:

  2. Use the information from webhook messages to monitor the status of the data you submitted.

Monitor the status of your level 2/3 data in webhooks

After you enable receiving data validation results in your webhook messages, use the information you receive in the webhook message to learn about the type of data Adyen submitted to Visa or Mastercard, or any errors.

  1. Use the enhancedSchemeDataSubmitted field to see which level of data (L2 or L3) Adyen successfully submitted to the schemes.
  2. If Adyen did not submit the data you sent, use the enhancedSchemeDataRefusalReason to learn the reason.
  3. Use the enhancedSchemeDataWarningReason to learn if Adyen dropped any of the optional the fields you sent.
  4. Use the feedback to fix the issues in your integration that caused the invalid data.

The following examples show different scenarios and the information you receive in the webhook messages.

If the level 3 data you sent was valid, and Adyen submitted it to Visa or Mastercard, you receive the following information in the webhook message.

If the level 2 data you sent was valid, and Adyen submitted it to Visa or Mastercard, you receive the following information in the webhook message.

If the level 3 data you sent contained errors, and Adyen only submits the level 2 data, you receive the following information in the webhook message.

If the card used to make the payment does not support level 2/3 data, you receive the following information in the webhook message.

If the data you sent included missing or incorrectly formatted fields for both level 2 and 3, and Adyen drops the full level 2/3 data, you receive the following information in the webhook message.

Test sending level 2/3 data

Use the following test card to make test payments with level 2/3 data:

Card Number Card scheme Expiry date Card security code
5555 5555 5555 4444 Mastercard 03/2030 737
4444 3333 2222 1111 Visa 03/2030 737

See also