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.

Enable risk results in the API response and webhooks

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

1. Log in to your Customer Area.
2. Go to Developers > Additional data.
3. Check the box under Risk > Fraud result.
4. 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.

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

1. Log in to your Customer Area.
2. Go to Revenue & risk > Settings.
3. Enable Change risk result format for custom rules.
4. 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 example:

fraudCheck-1-PaymentDetailRefCheck
fraudCheck-82-CustomFieldCheck

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 two 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.

{
   "live":"false",
   "notificationItems":[
      {
         "NotificationRequestItem":{
            "additionalData":{
               "fraudResultType":"GREEN",
               "fraudManualReview": "false",
               "fraudCheck-1-PaymentDetailRefCheck":"0",
               "fraudCheck-15-IssuingCountryReferral":"0",
               "fraudCheck-41-PaymentDetailNonFraudRefCheck":"50",
               "fraudCheck-82-CustomFieldCheck":"25",
               "totalFraudScore":"75"
            },
            "amount":{
               "currency":"USD",
               "value":10000
            },
            "eventCode":"AUTHORISATION",
            "eventDate":"2022-01-31T13:41:00+01:00",
            "merchantAccountCode":"YOUR_MERCHANT_ACCOUNT",
            "merchantReference":"YOUR_REFERENCE",
            "paymentMethod":"visa",
            "pspReference":"NC6HT9CRT65ZGN82",
            "reason":"",
            "success":"true"
         }
      }
   ]
}

API response

The following API response example includes two 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.

Example API response - one format for all checks

{
    "additionalData": {
        "paymentMethod": "visa",
        "fraudResultType": "GREEN",
        "fraudManualReview": "false"
    },
    "fraudResult": {
        "accountScore": 75,
        "results": [
            {
                "accountScore": 0,
                "checkId": 1,
                "name": "PaymentDetailRefCheck"
            },
            {
                "accountScore": 0,
                "checkId": 15,
                "name": "IssuingCountryReferral"
            },
            {
                "accountScore": 50,
                "checkId": 41,
                "name": "PaymentDetailNonFraudRefCheck"
            },
            {
                "accountScore": 25,
                "checkId": 82,
                "name": "CustomFieldCheck"
            }
        ]
    },
    "pspReference": "NC6HT9CRT65ZGN82",
    "resultCode": "Authorised",
    "amount": {
        "currency": "USD",
        "value": 10000
    },
    "merchantReference": "YOUR_REFERENCE"
}

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.

Standard risk rule result lines will be in this format: 

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

Custom risk rule result lines will be in this format: 

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

For example:
fraudCheck-1-PaymentDetailRefCheck
fraudCheck-82-CustomFieldCheck-YOUR_CUSTOM_RULE_1

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

Example webhook - split custom risk rules

The following webhook example includes two custom risk rules that triggered. When you choose option 2, all custom risk rules that triggered are shown as separate fraud checks.

{
   "live":"false",
   "notificationItems":[
      {
         "NotificationRequestItem":{
            "additionalData":{
               "fraudResultType":"GREEN",
               "fraudManualReview": "false",
               "fraudCheck-1-PaymentDetailRefCheck":"0",
               "fraudCheck-15-IssuingCountryReferral":"0",
               "fraudCheck-41-PaymentDetailNonFraudRefCheck":"50",
               "fraudCheck-82-CustomFieldCheck-YOUR_CUSTOM_RULE_1":"20",
               "fraudCheck-82-CustomFieldCheck-YOUR_CUSTOM_RULE_2":"5",
               "totalFraudScore":"75"
            },
            "amount":{
               "currency":"USD",
               "value":10000
            },
            "eventCode":"AUTHORISATION",
            "eventDate":"2022-01-31T13:41:00+01:00",
            "merchantAccountCode":"YOUR_MERCHANT_ACCOUNT",
            "merchantReference":"YOUR_REFERENCE",
            "paymentMethod":"visa",
            "pspReference":"KHQC5N7G84BLNK43",
            "reason":"",
            "success":"true"
         }
      }
   ]
}

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

{
    "additionalData": {
        "paymentMethod": "visa",
        "fraudResultType": "GREEN",
        "fraudManualReview": "false"
    },
    "fraudResult": {
        "accountScore": 75,
        "results": [
            {
                "accountScore": 0,
                "checkId": 1,
                "name": "PaymentDetailRefCheck"
            },
            {
                "accountScore": 0,
                "checkId": 15,
                "name": "IssuingCountryReferral"
            },
            {
                "accountScore": 50,
                "checkId": 41,
                "name": "PaymentDetailNonFraudRefCheck"
            },
            {
                "accountScore" : 5,
                "checkId" : 82,
                "name" : "CustomFieldCheck-YOUR_CUSTOM_RULE_1"
            },
            {
                "accountScore" : 20,
                "checkId" : 82,
                "name" : "CustomFieldCheck-YOUR_CUSTOM_RULE_2"
            },
        ]
    },
    "pspReference": "KHQC5N7G84BLNK43",
    "resultCode": "Authorised",
    "amount": {
        "currency": "USD",
        "value": 10000
    },
    "merchantReference": "YOUR_REFERENCE"
}

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 value.

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

{
   "live":"false",
   "notificationItems":[
      {
         "NotificationRequestItem":{
            "additionalData":{
               "fraudResultType":"GREEN",
               "fraudManualReview": "false",
               "fraudCheck-1-PaymentDetailRefCheck":"0",
               "fraudCheck-15-IssuingCountryReferral":"0",
               "fraudCheck-41-PaymentDetailNonFraudRefCheck":"50",
               "fraudCheck-82-CustomFieldCheck":"25",
               "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":"75"
            },
            "amount":{
               "currency":"USD",
               "value":10000
            },
            "eventCode":"AUTHORISATION",
            "eventDate":"2022-01-31T13:41:00+01:00",
            "merchantAccountCode":"YOUR_MERCHANT_ACCOUNT",
            "merchantReference":"YOUR_REFERENCE",
            "paymentMethod":"visa",
            "pspReference":"NC6HT9CRT65ZGN82",
            "reason":"",
            "success":"true"
         }
      }
   ]
}

Risk rule name reference

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