No momento, esta página não está disponível em português
Risk-management 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.

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 will affect the format of both webhooks and 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

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 Risk > Settings > Use new risk result format 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 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 Risk > Settings.
  3. Enable Use new risk result format.
  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.

Risk rule ID Name Name displayed in your Customer Area
1 PaymentDetailRefCheck Card/bank account number
2 CardChunkUsage Card number chunk used more than {times} times within {timespan} {units}
3 PaymentDetailUsage Card/bank account number used more than {times} times within {timespan} {units}
4 HolderNameUsage Card/bank account holder name used more than {times} times within {timespan} {units}
5 IPCountryReferral Shopper IP originates from high-risk country
6 ShopperIpRefCheck Shopper IP
7 ShopperIpUsage Shopper IP used more than {times} times within {timespan} {units}
8 ShopperEmailUsage Shopper email used more than {times} times within {timespan} {units}
9 ShopperIpIssuingCountry Shopper country differs from issuing country
10 HolderNameContainsNumber Card/bank account holder name contains a non-alphabetic character
11 HolderNameIsOneWord Card/bank account holder name is only one word
13 IssuerRefCheck Bank identification number (BIN)
15 IssuingCountryReferral Issuing country
20 AVSAuthResultCheck Billing address does not match cardholder address (AVS)
22 RegisteredShopperPaymentDetails Card/bank account number already used by another shopper
25 CVCAuthResultCheck Card Verification Code (CVC2/CVV2/CID) does not match
26 ShopperEmailRefCheck Shopper email
27 PmOwnerRefCheck Shopper name
29 LiabilityShiftCheck Liability shift status
33 AirlineOneWayTicketCheck Airline data one way ticket
34 AirlineLegCheck Airline data leg
35 TimeToDeliveryCheck Time to delivery
36 ShopperDistinctPaymentDetailsUsage Different cards/bank accounts used by the same shopper
37 ShopperDetailsUsage Shopper initiated a transaction more than {times} times within {timespan} {units}
38 PersistentCookieRefCheck Persistent cookie
40 ShopperAddressRefCheck Shopper address
41 PaymentDetailNonFraudRefCheck Card/bank account number non-fraud
46 DistinctCountryUsageByShopper Different countries used by shopper more than {times} times within {timespan} {units}
47 BlockedCardsUsageByShopper Issuer blocked (previous) card used by shopper
48 ChargebackCountByShopper Shopper has a previous fraud chargeback or notification of fraud
49 DistinctShopperIpUsageByShopper Multiple distinct IP addresses used by shopper more than {times} times within {timespan} {units}
50 DistinctShopperEmailUsageByShopper Multiple distinct email addresses used by shopper more than {times} times within {timespan} {units}
51 DistinctShopperReferenceUsageByShopper Multiple distinct shopper references used by shopper more than {times} times within {timespan} {units}
52 DistinctPaymentDetailUsageByShopper Multiple distinct cards/bank accounts used by shopper more than {times} times within {timespan} {units}
53 DistinctSharedShopperIpUsageByShopper Shopper used shared IP address
54 DistinctSharedPaymentDetailUsageByShopper Shopper used shared card/bank account more than {times} times within {timespan} {units}
55 ShopperAuthorisedFrequency Shopper authorised velocity exceeds {times} times within {timespan} {units}
56 ShopperReferenceCheck Shopper reference
57 BillingAddressDeliveryAddress Billing address differs from delivery address
62 DeliveryMethodCheck Delivery method
63 TransactionAmountCheck Transaction amount
64 TransactionAmountVelocity Authorised transaction amount velocity
65 EmailDomainRefCheck Email domain
66 PhoneNumberRefCheck Telephone number
67 SocialSecurityNumberRefCheck Social Security Number
68 TxVariantShopperReferenceRefCheck PayPal Payer ID
69 AutomatedReferralCheck Shopper automated referral
70 ShopperConsecutiveRefusalsCheck Shopper consecutive refusals exceeds {times} times within {timespan} {units}
71 LoyalShopperTrustCheck Trust loyal shoppers
72 TransactionTimeCheck Transaction time
73 PaymentMethodReferralCheck Payment method
74 EmailNameCheck Email address and shopper name comparison
75 PaymentDetailCarteBancaireRefCheck Carte Bancaire scheme blocked cards
77 EmailSyntaxCheck Email is likely to be fake or automatically generated
78 ShopperBehaviorCheck Fraudulent behavior on payment page
79 BinAttackRefCheck BIN attack
80 ShopperAccountAgeCheck Shopper account age
81 SchufaCheck SCHUFA
82 CustomFieldCheck Merchant defined name
83 DistinctAddressUsageByShopper Multiple distinct delivery addresses used by shopper more than {times} times within {timespan} {units}
84 PaymentDetailCUPRefCheck CUP scheme blocked cards
85 ShopperFraudRefusalsCheck Fraud refusals exceed {times} times within {timespan} {units}
86 PaymentDetailAmexRefCheck American Express scheme blocked cards
87 AcquirerResultEmailCheck PayPal auth-result email
88 AcquirerVerifiedShopperCheck PayPal verified shopper
89 AcquirerProtectionCheck PayPal protection eligibility
90 TxVariantCountryRefCheck PayPal account creation blocked country
91 ShopperStrongAuthenticationCheck Strong authentication confirmed {times} times in {timespan} {units}
92 TransactionHighAmountVelocityCheck High amount velocity
93 ShopperDeliveryAddressUsage Shopper delivery address used more than {times} times within {timespan} {units}