When you include level 2/3 enhanced scheme data (ESD) in your payment requests, the data you submit gets validated. Adyen may do one of the following in cases where the level 2/3 data you submit does not pass the validation:
- If a required field is missing or incorrectly formatted for both levels, drop the full level 2/3 data.
- If the card used in the transaction is only eligible for level 2 data, or the level 3 data is missing or incorrectly formatted, fallback to level 2 data.
- If an optional field is incorrectly formatted, drop the incorrectly formatted optional field.
You can optionally receive more 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.
You can get all information about level 2/3 data from additionalData in Standard webhooks, including the card type of the payment. Do not use the deprecated additionalData.cardSchemeEnhancedDataLevel object that was previously returned in the API responses of payment requests.
How it works
- Enable receiving level 2/3 data in webhooks.
- In your /payments, or /capture request, include level 2/3 data.
- After the payment has been captured, in the webhook you receive for the transaction, monitor the status of your level 2/3 data.
- If you use automatic capture you receive the information in an AUTHORISATION webhook. Because it includes level 2/3 data, the webhook is sent with a slight delay.
- If you use manual capture, or delayed automatic capture you receive the information in a CAPTURE webhook.
- If the level 2/3 data you submitted did not pass the data validation, refer to the webhook to learn about the reason. You can use this information to send the data correctly in future requests.
Enable receiving level 2/3 data information in webhooks
Update your webhook configuration to start receiving the information in AUTHORISATION, and CAPTURE webhooks.
- In your Customer Area, go to Developers > Webhooks.
- From the list of webhooks, select the one to configure.
- Select the edit icon .
- Under Additional Settings, select Include ESD Validation Result.
- Select Save configuration.
- (Conditional) 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 the AUTHORISATION webhook.
After the feature is enabled, the additionalData field in your webhooks contains the following information about the data validation:
| Field | Description |
|---|---|
enhancedSchemeDataReceived |
Indicates the type of data that we received from you. Possible values:
|
enhancedSchemeDataSubmitted |
Indicates the type of data that we submitted to Mastercard and Visa after data validation. Possible values:
|
enhancedSchemeDataRefusalReasons |
In case we drop all level 2/3 data because a required field is invalid or missing, this field informs you about the missing or wrong data that caused the error. |
enhancedSchemeDataWarningReasons |
In case we drop optional level 2/3 data fields you submitted, or we fall back to level 2 data, this field informs you about the reason. |
Make a payment with level 2/3 data
Use your integration to send level 2/3 data as you normally would.
When you are making a /payments, or /capture request, make sure that you follow the formatting requirements outlined in our /payments, or /capture reference.
Monitor the status of your level 2/3 data in webhooks
After you have enabled receiving data validation results in your webhooks, use the information you receive in the webhook to learn about the type of data Adyen submitted to Visa or Mastercard, or any errors.
- Check the
enhancedSchemeDataSubmittedfield to see what level of data (L2 or L3) was successfully submitted to the schemes. - If the data you sent was not submitted, check the
enhancedSchemeDataRefusalReasonto see why. - Check the
enhancedSchemeDataWarningReasonto learn if any of the optional the fields you submitted were dropped. - Use the feedback to fix the issues in your integration that caused the invalid data.
Below are some examples of the information that you can receive in your webhooks.
Valid level 3 data
If the level 3 data you submitted was valid and Adyen submitted it to Visa or Mastercard, you receive the following information in a webhook.
Valid level 2 data
If the level 2 data you submitted was valid and Adyen submitted it to Visa or Mastercard, you receive the following information in a webhook.
Level 2 fallback
If your request contains errors for level 3 data, and Adyen only submits the level 2 data, you receive the following information in a webhook.
Not eligible for level 2/3 data
If the card used to make this payment does not support level 2/3 data, you receive the following information in a webhook.
Invalid level 2/3 data
If the data you submit included missing or incorrectly formatted fields for both level 2 and 3, and Adyen drops the full level 2/3 data, the webhook you receive informs you about the issues. Below is an example additionalData field value that you may receive.
Testing
Use the following test card to test payments with level 2/3 data:
| Card Number | Card Type | Expiry Date | CVV |
|---|---|---|---|
| 5555 5555 5555 4444 | Mastercard | 03/2030 | 737 |