Level 2/3 data

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.

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:
   • Automatic capture and Delayed automatic capture: in the /payments request, include level 2/3 data in the enhancedSchemeData.levelTwoThree object.
   • Manual capture (Single partial capture and Multiple partial capture): in the /payments/{paymentPspReference}/captures request, include level 2/3 data in the enhancedSchemeData object.
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.
   • If you use automatic capture you receive the information in a webhook message with eventCode: AUTHORISATION.
   • If you use manual capture, or delayed automatic capture you receive the information in a webhook message with eventCode: 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 or /capture requests.
• Accurate and valid data.
• For Visa: the amount values you send must adhere to specific calculation guidelines.

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

Send level 2/3 data

1. Include level 2/3 data in the payment or capture request.

   • For the /payments request: include the additionalData.enhancedSchemeData object.
   • For the /payments/{paymentPspReference}/captures request: include the 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
   2 and 3	totalTaxAmount	totalTaxAmount
   3	itemDetailLine[itemNr].productCode	itemDetailLines.productCode
   3	itemDetailLine[itemNr].description	itemDetailLines.description
   3	itemDetailLine[itemNr].quantity	itemDetailLines.quantity
   3	itemDetailLine[itemNr].unitOfMeasure	itemDetailLines.unitOfMeasure
   3	itemDetailLine[itemNr].commodityCode	itemDetailLines.commodityCode
   3	itemDetailLine[itemNr].totalAmount	itemDetailLines.totalAmount
   3	itemDetailLine[itemNr].unitPrice	itemDetailLines.unitPrice
   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:

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.

Test sending level 2/3 data

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

See also

• Cards
• Enhanced scheme data
• Webhooks