Custom risk rules

In addition to using our standard risk rules, you can create your own custom risk rules. You can use these to influence the risk score of a transaction, send it to case management, or use the custom rule in combination with Dynamic 3D Secure.

Custom risk rules are a RevenueProtect premium feature.

To build your custom risk rules:

1. Choose risk variables: understand which Adyen-provided variables you can use in custom risk rules, or create custom fields.
2. Decide when your rule should trigger: before or after authorization.
3. Create the rule: set rule conditions to define when the rule should trigger.
4. Assign an action to the rule: define what should happen to the transaction when the rule triggers.
5. Test the rule.

With custom rules, you can address risks specific to your business. Custom rules provide a flexible way to supplement standard risk rules, and can help prevent specific types of potential fraud.
For a practical example, see the example scenario.

Step 1: Choose risk variables

The risk variables in your custom risk rules can be:

• Custom fields defined by you: create your own fields to use in custom rules.
• Risk fields provided by Adyen: use any of these fields in custom rules.

Create custom fields

1. Log in to your Customer Area and stay in your company account.
2. Go to Risk > Custom fields.
3. Under Custom fields, select New field, and provide the details for your custom field. The custom field name is case sensitive.

You assign a value to your custom field when you make a payment request, providing the riskdata.[customFieldName] in the additionalData object of your payment request.

For example, if you've created a custom field named userType, you can see how to assign a value to riskdata.userType in the Test the rule section.

Risk fields provided by Adyen

You can use Adyen-provided fields in your custom risk rule. To trigger the rule, many of these fields have to be included in the payment request.

To see which Adyen-provided risk fields you can use:

1. Log in to your Customer Area and stay in your company account.
2. Go to Risk > Custom fields.
3. Browse the Adyen provided field or fields that you can use. Possible categories:
   • ShopperDNA fields
   • Standard fields
   • Basket fields
     To be able to use basket fields in custom rules, provide basket item data using the following parameters in your payment request:
     • Checkout API v69 or earlier: additionalData.riskdata.basket.item
     • Checkout API v70 and later: lineItems
   • Promotion fields
   • Airline, airline leg and airline passenger fields
   • Velocity fields

After you have created custom fields or know which fields you want to use in your custom rule, the following steps explain how to use these fields as part of a custom risk rule.

Step 2: Decide when your custom rule should trigger

Before you create a custom risk rule, decide when you want to trigger the rule. This can be before or after authorization.

When you create a risk rule that triggers after authorization, you can take additional details from the authorization response into consideration. Examples of details that are available after authorization are the AVS response, the CVC response, or the liability shift status.

The variables that you use in your custom rule determine if the rule can be triggered before or after authorization:

Variable	Before authorization	After authorization
Adyen-provided fields
Custom fields
Custom lists

Step 3: Create the rule

To create a custom rule:

1. Log in to your Customer Area, and switch to the merchant account for which you want to create a custom rule.
2. Go to Risk > Risk profiles.
3. Select Manual risk > Custom rules.
4. Select + Create new custom rule and then select Pre auth or Post auth.
5. Enter a Rule Name.
6. Enter conditions. You can add conditions to the rule by selecting AND or OR. For each condition select:
   • Field Name - choose a risk variable, for example a custom field, an Adyen-provided risk field, or a list comparison.
   • Operator - how to compare the Field Name and the Field Value, for example GREATER THAN (>) or EQUALS (==).
   • Field Value - value that triggers your rule. If multiple values should trigger your rule, use commas to separate the values.
7. Select Save to finish creating the rule.

Step 4: Assign an action to the rule

Now that you created your custom rule, it is time to assign the action to take when the rule applies: modify the risk score, or send to case management.

To assign an action for the custom rule you created, configure the risk profile that contains the rule. A risk profile can apply to more than one merchant account.

Configure the risk profile containing the rule

You can configure a risk profile from either:

• A company account.
  Log in to your Customer Area, and stay in your company account. Select Risk > Risk profiles, and then select the risk profile that contains your custom rule. The risk profile overview page opens.
• A merchant account.
  Log in to your Customer Area, and select a merchant account that uses the risk profile that contains your custom rule. Select Risk > Risk profiles. The risk profile overview page opens.

Regardless where you configure the risk profile, the changes apply to all merchant accounts using that risk profile.

Assign an action to the custom rule

From the risk profile overview page:

1. Select Manual risk > Custom rules.
2. Select your custom rule.
3. Assign an action from the custom rule menu:
   • Increase or decrease total risk score by a given value. For more information on fraud scores, see How does the fraud score work?.
   • Send to case management for manual review. For more information on how to manually review transactions, see Case management.
4. Select Save changes.

Now that you have created your custom rule, and assigned an action, you can also use it as one of the risk checks to be applied when configuring Dynamic 3D Secure.

Step 5: Test the rule

The following example /payments requests are based on the example scenario Guest user buys too many restricted products.

1. Make a POST request to the /payments endpoint, including the risk fields that your custom rule uses:

  {
     "amount":{
        "currency":"USD",
        "value":1000
     },
     "reference":"98739872454D",
     "paymentMethod": {
        "type": "scheme",
        "encryptedCardNumber": "test_4111111111111111",
        "encryptedExpiryMonth": "test_03",
        "encryptedExpiryYear": "test_2030",
        "encryptedSecurityCode": "test_737"
     },
     "returnUrl":"https://your-company.com/...",
     "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
     "additionalData":{
       "riskdata.basket.item1.productTitle":"Golden shoes",
       "riskdata.basket.item1.quantity": "3",
       "riskdata.userType": "Guest"
     }
  }

2. Take note of the pspReference in the payment response.
3. Log in to your Customer Area.
4. In the Search payments, select Payments and search for the pspReference value.
5. Select the number listed under Risk score for your payment. A page will open with a breakdown of which fraud checks triggered.

Optional: Create a custom list comparison

A custom list comparison lets you compare risk field values against block and trust lists, which includes custom lists. For custom lists you can add expiry dates for list entries. Field values are only compared against list entries that have not expired.

For example, in the example scenario Guest user buys too many restricted products, you use a custom list to check if a shopper buys more than two items from a list of restricted items that you define.

You first create your custom list containing restricted items. Then, you create the list comparison that checks if the shopper's basket has any restricted items:

1. Create your list:

   1. From your Customer Area company account, go to Risk > Block and trust lists.
   2. Select Create new list.
   3. Enter the list name and select Create list.

2. Select the list you just created and add items to it. You can either:

   • Select Add item and provide details for your entry:
     • Item: The list item. For example, a product title for a restricted item.
     • Reason: (Optional) Any information useful to you about why the item is part of the list.
     • Expire date: (Optional) Expiry date for the list entry. The date must be in the future and if empty, we assign 9999-12-30 23:00:00+01.

   • Select Upload CSV and upload a CSV file containing your list.

     To create a CSV file:

     1. Create a spreadsheet file. In the first row of the file, write the following headers: item, reason, and expiredate.

     2. In the next rows, add the item and provide details for your entry in the spreadsheet.

        • item: The list item. For example, a product title for a restricted item.
        • reason: (Optional) Any information useful to you about why the item is part of the list.
        • expiredate: (Optional) Expiry date for the list entry. The date must be in the future and if empty, we assign 9999-12-30 23:00:00+01.

        Example:

        item	reason	expiredate
        Signature shirt	Limited edition	2023-11-10
        Golden shoes
        Designer bag	Limited edition
        Vintage hat		2023-12-30

     3. Save the spreadsheet in CSV format.

     4. Upload the CSV file to your custom list.

3. Define the list comparison:

   1. Go to Risk > Custom fields.
   2. Under List comparisons, select New list comparison and provide the details for your comparison:
      • Name: A name for the list comparison. It must not contain spaces.
      • Description: A description of the comparison.
      • Field for comparison: Select a custom risk field you defined or an Adyen-provided field.
      • List: Select a custom list you defined or another block and trust list.
   3. Select Save.

Example scenario

The following scenario is an example of how you can set up and use custom rules and custom list comparisons.

A guest user buys too many restricted items

As a webshop owner you find out certain purchases by a guest user have an increased fraud risk. You decide to build a custom rule to offset this risk.

Your custom rule adds 20 risk points if the shopper:

• Is a guest user.
• Is buying more than 2 items from a list of restricted products.

Step 1: Set up risk variables

For this example scenario, you need all variables:

• To use the shopper's basket items in your rule:
  • Provide basket item data using the following parameters in your payment request:
    • Checkout API v69 or earlier: additionalData.riskdata.basket.item
    • Checkout API v70 and later: lineItems
• For the user type, you need to create a custom field with the following details:
  • Name: userType
  • Data type: String
  • Field description: The type of user making the payment

Step 2: Decide when to trigger your custom rule

You don't have to take into consideration details from the authorization response, and will create a pre auth rule.

Step 3: Create the rule

For this example scenario:

1. Select Pre auth when creating the rule, because you're using custom lists which can only be used before authorization.
2. Name the rule guestBuysTooManyRestrictedProducts.

3. Fill in the conditions for the rules:

   Field Name	Operator	Field Value	Corresponding payment request field
   userType (String)	EQUALS (==)	Guest	additionalData.riskdata.userType
   quantity (Number)	GREATER THAN (>)	2	Checkout API v69 and earlier: additionalData.riskdata.basket.item[itemNr].quantity Checkout API v70 and later: lineItems.quantity
   restrictedProduct (Boolean)	EQUALS (==)	True	Checkout API v69 and earlier: additionalData.riskdata.basket.item[itemNr].productTitle Checkout API v70 and later: lineItems.description

Step 4: Assign an action

For this example scenario, select the custom rule you created, guestBuysTooManyRestrictedProducts, and increase the risk score by 20.

Mandatory for this scenario: create a custom list comparison

To check the items in the shopper's basket against your list of restricted products, you need to create a custom list comparison.

That means you have to create custom list comparison, and create a custom list called Restricted items.

Create a custom list comparison:

• Name: restrictedProduct
• Description: Check if a shopper is buying any items with a restricted product title.
• Field for comparison: productTitle, an Adyen-provided risk field. You assign the value of this field when you make a payments request. For an example, see the Test the rule section.
• List: Restricted items, the custom list you created.

Step 5: Test the rule

In the Test the rule section you can find an example payment request for this specific scenario.

See also