---
title: "Level 2/3 data"
description: "Include level 2/3 data in your requests for US payments with Mastercard and Visa."
url: "https://docs.adyen.com/payment-methods/cards/enhanced-scheme-data/l2-l3"
source_url: "https://docs.adyen.com/payment-methods/cards/enhanced-scheme-data/l2-l3.md"
canonical: "https://docs.adyen.com/payment-methods/cards/enhanced-scheme-data/l2-l3"
last_modified: "2023-03-09T17:11:00+01:00"
language: "en"
---

# Level 2/3 data

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

[View source](/payment-methods/cards/enhanced-scheme-data/l2-l3.md)

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](/payment-methods/cards/enhanced-scheme-data#types-and-industries), 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](/payment-methods/cards/enhanced-scheme-data#requirements), 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](/payment-methods/cards/enhanced-scheme-data#types-and-industries), 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](/development-resources/webhooks).

1. Review the [data validation](#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](#enable-receiving-level-23-data-in-webhooks) in webhook messages.

3. [Send level 2/3 data](#send-level23-data) in your payment or capture request for a transaction. The request you send it in depends on your [capture setting](/online-payments/capture#types-of-capture):

   * **Automatic capture** and **Delayed automatic capture**: in the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request, include level 2/3 data in the [enhancedSchemeData.levelTwoThree](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#requestenhancedSchemeData-levelTwoThree) object.
   * **Manual capture** (**Single partial capture** and **Multiple partial capture**): in the [/payments/{paymentPspReference}/captures](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/\(paymentPspReference\)/captures) request, include level 2/3 data in the [enhancedSchemeData](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/\(paymentPspReference\)/captures#request-enhancedSchemeData-levelTwoThree) object.

4. After the payment has been captured, [monitor the status of your level 2/3 data](#monitor-the-status-of-your-level-23-data) using the information in the webhook message that you receive.

   * If you use [automatic capture](/online-payments/capture/#automatic-capture) you receive the information in a webhook message with `eventCode`: [AUTHORISATION](https://docs.adyen.com/api-explorer/Webhooks/latest/post/AUTHORISATION).
   * If you use [manual capture](/online-payments/capture/#manual-capture?target=_blank), or [delayed automatic capture](/online-payments/capture/#capture-delay?target=_blank) you receive the information in a webhook message with `eventCode`: [CAPTURE](https://docs.adyen.com/api-explorer/Webhooks/latest/post/CAPTURE).

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:

* Format requirements for the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-additionalData-AdditionalDataLevel23) or [/capture](https://docs.adyen.com/api-explorer/Payment/latest/post/capture#request-additionalData-AdditionalDataLevel23) requests.
* Accurate and valid data.
* For Visa: the amount values you send must adhere to specific [calculation guidelines](#amount-calculations).

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: `enhancedSchemeData.itemDetailLine1.totalAmount` = (`enhancedSchemeData.itemDetailLine1.quantity` x `enhancedSchemeData.itemDetailLine1.unitPrice`) - `enhancedSchemeData.itemDetailLine1.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: `modificationAmount {amount}` = `enhancedSchemeData.itemDetailLine1.totalAmount` + `enhancedSchemeData.itemDetailLine2.totalAmount` + `enhancedSchemeData.freightAmount` + `enhancedSchemeData.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](https://docs.adyen.com/api-explorer/Webhooks/latest/post/AUTHORISATION) and `eventCode`: [CAPTURE](https://docs.adyen.com/api-explorer/Webhooks/latest/post/CAPTURE).

1. In your [Customer Area](https://ca-test.adyen.com/), 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](/online-payments/capture/#automatic-capture) or send the L2/3 data in the payment request, ask our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to enable receiving information about level 2/3 data in webhook messages with `eventCode`: [AUTHORISATION](https://docs.adyen.com/api-explorer/Webhooks/latest/post/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 payment or capture request.

   * For the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request: include the [additionalData.enhancedSchemeData](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-additionalData-AdditionalDataLevel23-enhancedSchemeData-customerReference) object.
   * For the [/payments/{paymentPspReference}/captures](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/\(paymentPspReference\)/captures) request: include the [enhancedSchemeData.levelTwoThree](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/\(paymentPspReference\)/captures#request-enhancedSchemeData-levelTwoThree) object.\
     The following table shows which level 2/3 data fields are required and optional, depending on the type of request.

   | Level   | Payment request fields                  | Capture request fields           | Required                                                                                    |
   | ------- | --------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------- |
   | 2 and 3 | `customerReference`                     | `customerReferenceNumber`        | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") |
   | 2 and 3 | `totalTaxAmount`                        | `totalTaxAmount`                 | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") |
   | 3       | `itemDetailLine[itemNr].productCode`    | `itemDetailLines.productCode`    | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") |
   | 3       | `itemDetailLine[itemNr].description`    | `itemDetailLines.description`    | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") |
   | 3       | `itemDetailLine[itemNr].quantity`       | `itemDetailLines.quantity`       | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") |
   | 3       | `itemDetailLine[itemNr].unitOfMeasure`  | `itemDetailLines.unitOfMeasure`  | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") |
   | 3       | `itemDetailLine[itemNr].commodityCode`  | `itemDetailLines.commodityCode`  | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") |
   | 3       | `itemDetailLine[itemNr].totalAmount`    | `itemDetailLines.totalAmount`    | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") |
   | 3       | `itemDetailLine[itemNr].unitPrice`      | `itemDetailLines.unitPrice`      | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") |
   | 3       | `destinationCountryCode`                | `destination.countryCode`        |                                                                                             |
   | 3       | `destinationPostalCode`                 | `destination.postalCode`         |                                                                                             |
   | 3       | `destinationStateProvinceCode`          | `destination.stateOrProvince`    |                                                                                             |
   | 3       | `dutyAmount`                            | `dutyAmount`                     |                                                                                             |
   | 3       | `freightAmount`                         | `freightAmount`                  |                                                                                             |
   | 3       | `orderDate`                             | `orderDate`                      |                                                                                             |
   | 3       | `shipFromPostalCode`                    | `shipFromPostalCode`             |                                                                                             |
   | 3       | `itemDetailLine[itemNr].discountAmount` | `itemDetailLines.discountAmount` |                                                                                             |

   Select the endpoint for the corresponding request example:

   ### Tab: `/payments` endpoint

   **Example payment request with level 2/3 data**

   ```bash
   curl https://checkout-test.adyen.com/v72/payments \
   -H 'x-API-key: ADYEN_API_KEY' \
   -H 'idempotency-key: YOUR_IDEMPOTENCY_KEY' \
   -H 'content-type: application/json' \
   -X POST
   -d '{
     "amount": {
       "currency": "USD",
       "value": 200000
     },
     "reference": "YOUR_ORDER_NUMBER",
     "paymentMethod":{
       "type":"scheme",
       "cvc": "737",
       "expiryMonth": "03",
       "expiryYear": "2030",
       "holderName": "John Smith",
       "number": "5555555555554444"
     },
     "returnUrl": "https://your-company.example.com/...",
     "merchantAccount": "ADYEN_MERCHANT_ACCOUNT",
     "additionalData": {
        "enhancedSchemeData.totalTaxAmount": "20000",
        "enhancedSchemeData.customerReference": "101",
        "enhancedSchemeData.freightAmount": "10000",
        "enhancedSchemeData.dutyAmount": "5000",
        "enhancedSchemeData.shipFromPostalCode": "1011DJ",
        "enhancedSchemeData.orderDate": "010123",
        "enhancedSchemeData.destinationPostalCode": "10003",
        "enhancedSchemeData.destinationStateProvinceCode": "NYC",
        "enhancedSchemeData.destinationCountryCode": "USA",
        "enhancedSchemeData.itemDetailLine1.description": "T15 Test products 1",
        "enhancedSchemeData.itemDetailLine1.productCode": "TEST120",
        "enhancedSchemeData.itemDetailLine1.commodityCode": "COMMCODE1",
        "enhancedSchemeData.itemDetailLine1.quantity": "9",
        "enhancedSchemeData.itemDetailLine1.unitOfMeasure": "m",
        "enhancedSchemeData.itemDetailLine1.unitPrice": "10000",
        "enhancedSchemeData.itemDetailLine1.discountAmount": "5000",
        "enhancedSchemeData.itemDetailLine1.totalAmount": "85000",
        "enhancedSchemeData.itemDetailLine2.description": "T15 Test products 2",
        "enhancedSchemeData.itemDetailLine2.productCode": "TEST120",
        "enhancedSchemeData.itemDetailLine2.commodityCode": "COMMCODE2",
        "enhancedSchemeData.itemDetailLine2.quantity": "9",
        "enhancedSchemeData.itemDetailLine2.unitOfMeasure": "m",
        "enhancedSchemeData.itemDetailLine2.unitPrice": "10000",
        "enhancedSchemeData.itemDetailLine2.discountAmount": "5000",
        "enhancedSchemeData.itemDetailLine2.totalAmount": "85000"
     }
   }'
   ```

   **Example response to a payment request with level 2/3 data**

   ```json
   {
      "pspReference":"8915844059375211",
      "resultCode":"Authorised",
      "authCode":"506847",
      "additionalData":{
         "cardSchemeEnhancedDataLevel":"L2",
         "cardPaymentMethod":"visa",
         "cardIssuingBank":"Bank of America",
         "cardIssuingCountry":"US",
         "cardIssuingCurrency":"USD",
         "cardBin":"411111",
         "fundingSource":"CREDIT"
      }
   }
   ```

   ### Tab: `/captures` endpoint

   **Example capture request with level 2/3 data**

   ```bash
   curl https://checkout-test.adyen.com/v72/payments/WNS7WQ756L2GWR82/captures \
   -H 'x-API-key: ADYEN_API_KEY' \
   -H 'idempotency-key: YOUR_IDEMPOTENCY_KEY' \
   -H 'content-type: application/json' \
   -X POST
   -d '{
      "merchantAccount":"ADYEN_MERCHANT_ACCOUNT",
      "amount":{
         "currency":"USD",
         "value":200000
      },
      "originalReference":"NC6HT9CRT65ZGN82",
      "enhancedSchemeData.levelTwoThree":{
         "totalTaxAmount": "20000",
         "customerReferenceNumber": "101",
         "freightAmount": "10000",
         "dutyAmount": "5000",
         "shipFromPostalCode": "1011DJ",
         "orderDate": "010123",
         "destination": {
             "postalCode": "10003",
             "stateOrProvince": "NYC",
             "countryCode": "USA"
         },
         "itemDetailLine": [
            {
               "description": "T15 Test products 1",
               "productCode": "TEST120",
               "commodityCode": "COMMCODE1",
               "quantity": "9",
               "unitOfMeasure": "m",
               "unitPrice": "10000",
               "discountAmount": "5000",
               "totalAmount": "85000"
            },
            {
               "description": "T15 Test products 2",
               "productCode": "TEST120",
               "commodityCode": "COMMCODE2",
               "quantity": "9",
               "unitOfMeasure": "m",
               "unitPrice": "10000",
               "discountAmount": "100",
               "totalAmount": "85000"
            }
         ]
      }
   }'
   ```

2. Use the information from webhook messages to [monitor the status of the data you submitted](#monitor-the-status-of-your-level-23-data).

## 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.

**

### Valid level 3 data

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.

**Example object for valid level 3 data**

```json
"additionalData": {
   "enhancedSchemeDataReceived": "L3",
   "enhancedSchemeDataRefusalReasons": "",
   "enhancedSchemeDataWarningReasons": "",
   "enhancedSchemeDataSubmitted": "L3"
}
```

**

### Valid level 2 data

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.

```json
"additionalData": {
   "enhancedSchemeDataReceived": "L2",
   "enhancedSchemeDataRefusalReasons": "",
   "enhancedSchemeDataWarningReasons": "",
   "enhancedSchemeDataSubmitted": "L2"
}
```

**

### Level 3 data contained errors

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.

```json
"additionalData": {
   "enhancedSchemeDataReceived": "L3",
   "enhancedSchemeDataRefusalReasons": "",
   "enhancedSchemeDataWarningReasons": "L3 downgraded to L2 due to invalid data",
   "enhancedSchemeDataSubmitted": "L2"
}
```

**

### Not eligible for level 2/3 data

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

```json
"additionalData": {
   "enhancedSchemeDataReceived": "L3",
   "enhancedSchemeDataRefusalReasons": "Card type doesn't support ESD",
   "enhancedSchemeDataWarningReasons": "",
   "enhancedSchemeDataSubmitted": ""
}
```

**

### Invalid level 2/3 data

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.

```json
"additionalData": {
   "enhancedSchemeDataReceived": "L3",
   "enhancedSchemeDataRefusalReasons": "Line item total amount must be (quantity * unit cost) - discount per line item",
   "enhancedSchemeDataWarningReasons": "L3 downgraded to L2 due to invalid data",
   "enhancedSchemeDataSubmitted": ""
}
```

## 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

* [Cards](/payment-methods/cards)
* [Enhanced scheme data](/payment-methods/cards/enhanced-scheme-data)
* [Webhooks](/development-resources/webhooks)
