Risk-team icon

Fraud results in API responses and webhooks

Learn how to include risk information and results in the API response and webhooks to inform you when payment requests trigger risk rules.

View source

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.

Returning fraud results is not turned on by default. When you configure your account to include risk information, it affects the format of both webhooks and the payment response.

Requirements

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

Requirement Description
Integration type Make sure that you have built an online payments integration and that risk is enabled.
Customer Area roles To manage webhooks and what is returned in the API response, make sure that you have the following role(s):
  • Merchant technical integrator
To manage risk settings, make sure that you have one of the following role(s):
  • Merchant change risk settings
  • Risk admin
Limitations You can only return information about custom risk rules and the fraud risk level when you have enabled premium features.
Setup steps Before you begin:

How it works

  1. Enable risk results in the API response and webhooks.
  2. 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 are important values that you can get in the API response or webhooks:

  • The possible fraudResultType values are GREEN, AMBER, or RED. For Protect premium, AMBER means that the transaction has been sent to case management for manual review.
  • The possible fraudRiskLevel values are veryLow, low, medium, high or veryHigh. For Protect premium, the risk level shows the classification by the Machine learning: fraud risk rule.
  • For any field that shows a fraud score, for example accountScore or totalFraudScore, the possible values are -100, 0, 100 or 200.

Overview of options

Category Customer Area Setting Description Comment
Fraud results Developers > Additional data > Risk > Fraud result ON
OFF		 Return / Do not return risk information in additionalData and fraudResult object of the API response and webhook. ON: Required for option 1 and option 2.
Custom rules format Revenue & risk > Settings > Change risk result format for custom rules ON
OFF		 Return / Do not return each custom risk checks that triggered separately in the fraudResult object of the API response and webhook. ON: Required for option 2.
Standard webhook Developers > Webhooks > Webhook settings > Additional settings > Risk > Include Risk Data ON
OFF		 Include / Do not include risk data sent in the request, such as custom fields, as riskdata in the webhook. ON: Required for option 3.

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 the 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, in your Customer Area.

  1. Go to Developers > Webhooks.
  2. Next to Standard webhook, select the edit webhook icon .
  3. Under Additional Settings > Risk, select the edit icon .
  4. Select Include Risk Data.
  5. 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 example includes 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 example includes more than one risk rules that triggered. When you choose option 1, if one or more (custom) rules trigger, all results are shown in the same way.

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 example includes 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.

Risk rule result lines will be in this format: 

fraudCheck-82-CustomFieldCheck-[Rule name]

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

API response

The following API response example includes 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 table as a reference for risk rules that can appear in your API response or webhooks.

Protect risk rules

Names of Adyen-provided rules contain spaces. Names of any custom rules that you create cannot contain spaces.

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 -white_check_mark-
Custom rules The rule name, without spaces, as used in the custom rule configuration. Block -white_check_mark-
Refund abuse risk Refund abuse risk Review -white_check_mark-
Refund abuse risk Refund abuse risk - high risk Block -white_check_mark-
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

See also