--- title: "Fraud results in API responses and webhooks" description: "Learn how to include risk information and results in the API response and webhooks to inform you when payment requests trigger risk rules." url: "https://docs.adyen.com/risk-management/handle-risk-rule-notifications" source_url: "https://docs.adyen.com/risk-management/handle-risk-rule-notifications.md" canonical: "https://docs.adyen.com/risk-management/handle-risk-rule-notifications" last_modified: "2019-10-21T15:46:00+02:00" language: "en" --- # 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](/risk-management/handle-risk-rule-notifications.md) [Webhooks](/development-resources/webhooks/) inform your server of [payment events](/account/payments-lifecycle), [modifications](/online-payments/modify-payments), and newly available [reports](/reporting). 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](/online-payments/build-your-integration/) and that [risk is enabled](/risk-management/configure-risk-settings/). | | **[Customer Area roles](/account/user-roles/#risk)** | 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](/risk-management/configure-risk-settings#risk-general). | | **Setup steps** | Before you begin:- Set up [risk management](/risk-management/). - Configure and enable [webhooks](/development-resources/webhooks/). | ## How it works 1. [Enable](#risk-result-enable) risk results in the API response and webhooks. 2. Decide in [which format](#risk-result-options) 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](https://ca-test.adyen.com/): 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](/risk-management/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](/risk-management/configure-your-risk-profile/machine-learning-rules/)** 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](#version-1) and [option 2](#version-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](#version-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](#version-3). | ### Option 1 If you want to return all [risk rule result lines in one format](#version-1) in the [API response](#api-response-example) and [webhooks](#notification-example), including any custom rules, [enabling](#risk-result-enable) the **Fraud result** in **Additional data** is all you need to do. ### Option 2 If you want to break down [custom risk rules separately](#version-2) in the [API response](#api-response-example-1) and [webhooks](#notification-example-1), you also have to enable the following risk setting in your [Customer Area](https://ca-test.adyen.com/): 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](#version-3) that were included in the request in [webhooks](#notification-example-2), in your [Customer Area](https://ca-test.adyen.com/). 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](#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. **Example webhook - one format for all checks** ```json { "live":"false", "notificationItems":[ { "NotificationRequestItem":{ "additionalData":{ "fraudResultType":"RED", "fraudRiskLevel":"high", "fraudManualReview": "false", "fraudCheck-82-CustomFieldCheck": "100" "totalFraudScore":"100" }, "amount":{ "currency":"EUR", "value":30 }, "eventCode":"AUTHORISATION", "eventDate":"2025-03-31T13:41:00+01:00", "merchantAccountCode":"YOUR_MERCHANT_ACCOUNT", "merchantReference":"YOUR_REFERENCE", "paymentMethod":"visa", "pspReference":"NC6HT9CRT65ZGN82", "reason":"FRAUD-CANCELLED", "success":"false" } } ] } ``` ### 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 **Example API response - one format for all checks** ```json { "additionalData": { "paymentMethod": "visa", "fraudResultType": "RED", "fraudRiskLevel":"high", "fraudManualReview": "false" }, "fraudResult": { "accountScore": 100, "results": [ { "accountScore": -100, "checkId": 82, "name": "CustomFieldCheck" }, { "accountScore": 200, "checkId": 82, "name": "CustomFieldCheck" } ] }, "pspReference": "NC6HT9CRT65ZGN82", "refusalReason": "FRAUD-CANCELLED", "resultCode": "Cancelled", "amount": { "currency": "EUR", "value": 30 }, "merchantReference": "YOUR_REFERENCE" } ``` For more information on the fields returned in the API response, see our [API Explorer](https://docs.adyen.com/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](#risk-rule-name-reference). **Example webhook - split custom risk rules** ```json { "live":"false", "notificationItems":[ { "NotificationRequestItem":{ "additionalData":{ "fraudResultType":"RED", "fraudRiskLevel":"high", "fraudManualReview": "false", "fraudCheck-82-CustomFieldCheck-YOUR_CUSTOM_RULE_1": "-100" "fraudCheck-82-CustomFieldCheck-YOUR_CUSTOM_RULE_2": "200" "fraudCheck-82-CustomFieldCheck-Card number or bank account number block list": "0" "totalFraudScore":"100" }, "amount":{ "currency":"EUR", "value":30 }, "eventCode":"AUTHORISATION", "eventDate":"2025-03-31T13:41:00+01:00", "merchantAccountCode":"YOUR_MERCHANT_ACCOUNT", "merchantReference":"YOUR_REFERENCE", "paymentMethod":"visa", "pspReference":"NC6HT9CRT65ZGN82", "reason":"FRAUD-CANCELLED", "success":"false" } } ] } ``` ### 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 **Example API response - split custom risk rules** ```json { "additionalData": { "paymentMethod": "visa", "fraudResultType": "RED", "fraudRiskLevel":"high", "fraudManualReview": "false" }, "fraudResult": { "accountScore": 100, "results": [ { "accountScore": -100, "checkId": 82, "name": "CustomFieldCheck-YOUR_CUSTOM_RULE_1" }, { "accountScore": 200, "checkId": 82, "name": "CustomFieldCheck-YOUR_CUSTOM_RULE_2" }, { "accountScore": 0, "checkId": 82, "name": "CustomFieldCheck-Card number or bank account number block list" } ] }, "pspReference": "NC6HT9CRT65ZGN82", "refusalReason": "FRAUD-CANCELLED", "resultCode": "Cancelled", "amount": { "currency": "EUR", "value": 30 }, "merchantReference": "YOUR_REFERENCE" } ``` For more information on the fields returned in the API response, see our [API Explorer](https://docs.adyen.com/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](#version-1)), and custom risk rules with custom fields triggered. #### Example webhook including risk data **Example webhook including risk data** ```json { "live":"false", "notificationItems":[ { "NotificationRequestItem":{ "additionalData":{ "fraudResultType":"RED", "fraudRiskLevel":"high", "fraudManualReview": "false", "fraudCheck-82-CustomFieldCheck":"100", "riskdata.userType":"Guest", "riskdata.basket.item1.productTitle":"Golden shoes", "riskdata.basket.item1.quantity":"3", "riskdata.basket.item2.productTitle":"Silver shoes", "riskdata.basket.item2.quantity":"5", "totalFraudScore":"100" }, "amount":{ "currency":"EUR", "value":30 }, "eventCode":"AUTHORISATION", "eventDate":"2025-03-31T13:41:00+01:00", "merchantAccountCode":"YOUR_MERCHANT_ACCOUNT", "merchantReference":"YOUR_REFERENCE", "paymentMethod":"visa", "pspReference":"NC6HT9CRT65ZGN82", "reason":"FRAUD-CANCELLED", "success":"false" } } ] } ``` ## 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-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Custom rules | The rule name, without spaces, as used in the custom rule configuration. | Block | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Refund abuse risk | Refund abuse risk | Review | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | | Refund abuse risk | Refund abuse risk - high risk | Block | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-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 * [Webhooks](/development-resources/webhooks) * [Additional webhooks settings](/development-resources/webhooks/webhook-types/additional-settings) * [Configure custom rules](/risk-management/configure-your-risk-profile/custom-rules)