Fraud results in API responses and webhooks

Webhooks inform your server of payment events, modifications, and newly available reports. Webhooks can also inform you when payment requests trigger risk rules.

You can include risk information, such as whether a payment was sent to case management, and which risk rules triggered in these webhooks, as well as in the payment response.

Requirements

Before you begin, take into account the following requirements and limitations.

How it works

1. Determine which risk engine you are using, the classic risk engine (RevenueProtect) or the latest risk engine (Protect).
2. Enable risk results in the API response and webhooks.
3. Decide in which format you want to return fraud results.

Enable risk results in the API response and webhooks

To get risk information and fraud results in the API response and in webhooks:

In your Customer Area:

1. Go to Developers > Additional data.
2. Check the box under Risk > Fraud result.
3. Select Save configuration.

When enabled:

• In the API response, the additionalData object contains risk information, and the fraudResult object shows which risk rules triggered.
• In the webhook, the additionalData object contains both risk information and the fraud results.

The following list contains the most important similarities and differences between the classic (RevenueProtect) and latest risk engine (Protect):

• For both Protect and RevenueProtect, the possible fraudResultType values are GREEN, AMBER, and RED.
• For Protect premium, the fraudRiskLevel value shows the risk level classification by the Machine learning: fraud risk rule. Possible values are veryLow,low, medium, high or veryHigh.
• For Protect, possible risk scores values can be -100, 0, or 200.
• For RevenueProtect, possible risk score values range from -100 to 100.

Overview of options

Option 1

If you want to return all risk rule result lines in one format in the API response and webhooks, including any custom rules, enabling Fraud result in Additional data is all you need to do.

Option 2

If you want to break down custom risk rules separately in the API response and webhooks, you also have to enable the following risk setting:

In your Customer Area:

1. Go to Revenue & risk > Settings.
2. Enable Change risk result format for custom rules.
3. Select Save configuration.

Option 3

This setting is optional and only affects webhooks.

If you want to return any custom risk fields that were included in the request in webhooks:

1. Log in to your Customer Area.
2. Go to Developers > Webhooks.
3. Next to Standard webhook, select the edit webhook icon .
4. Under Additional Settings > Risk, select the edit icon .
5. Select Include Risk Data.
6. Select Apply.

Option 1: One format for all risk checks

Webhooks

All risk rule result lines in webhooks will be in the format: 

fraudCheck-[risk rule ID]-[risk rule name]

For a list of the risk rule names, see the risk rule name reference.

Example webhook - one format for all checks

The following webhook examples include more than one custom risk rule that triggered. When you choose option 1, if one or more custom rules trigger, all custom risk rules are grouped under one fraud check.

API response

The following API response examples include more than one custom risk rules that triggered. When you choose option 1, if one or more custom rules trigger, all custom risk rules are grouped under one fraud check result when you use RevenueProtect.

Example API response - one format for all checks

For more information on the fields returned in the API response, see our API Explorer.

Option 2: Return custom risk rules in a different format

Webhooks

You can break custom risk rules into separate, more specific, rules. This lets you track when specific custom risk rules triggered.

Example webhook - split custom risk rules

The following webhook examples include more than one custom risk rules that triggered. When you choose option 2, all custom risk rules that triggered are shown as separate fraud checks.

API response

The following API response examples include two custom risk rules.
When you choose option 2, all custom risk rules that triggered are shown as separate fraud check results.

Example API response - split custom risk rules

For more information on the fields returned in the API response, see our API Explorer.

Option 3: Return risk data in webhooks

When you turn on the optional setting Include Risk Data in your webhook configuration, if you use custom risk rules, the webhook also contains the custom riskdata fields sent in the request, and their values.

Here is an example webhook where all fraud checks are returned in one format (option 1), and custom risk rules with custom fields triggered.

Example webhook including risk data

Risk rule name reference

Use the following tables as a reference for risk rules that can appear in your API response or webhooks for Protect or RevenueProtect.

Protect reference

Both Adyen-provided and custom rules are categorized as CustomFieldCheck.

Risk rule type	Risk rule	Action	Requires premium
Machine learning	Machine learning rule: bot attack risk	Block
Machine learning	Machine learning rule: fraud risk	Block
Custom rules	The rule name, without spaces, as used in the custom rule configuration.	Block
Refund abuse risk	Refund abuse risk	Review
Refund abuse risk	Refund abuse risk - high risk	Block
Risk list	Bank identification number allow list	Allow
Risk list	Bank identification number block list	Block
Risk list	Card number or bank account number allow list	Allow
Risk list	Card number or bank account number block list	Block
Risk list	Issuing Country block list	Block
Risk list	Non-fraudulent card number or bank account number block list	Block
Risk list	Phone number allow list	Allow
Risk list	Phone number block list	Block
Risk list	Shopper Address allow list	Allow
Risk list	Shopper Address block list	Block
Risk list	Shopper IP Address allow list	Allow
Risk list	Shopper IP Address block list	Block
Risk list	Shopper IP Country block list	Block
Risk list	Shopper email allow list	Allow
Risk list	Shopper email block list	Block
Risk list	Shopper email domain allow list	Allow
Risk list	Shopper email domain block list	Block
Risk list	Shopper name allow list	Allow
Risk list	Shopper name block list	Block
Risk list	Shopper reference allow list	Allow
Risk list	Shopper reference block list	Block
Risk list	Social Security Number allow list	Allow
Risk list	Social Security Number block list	Block

RevenueProtect reference

Use the following table to reference risk rule IDs to their corresponding names.

See also