# Create risk rules and lists When building risk strategies for the [Fraud Detection](https://www.checkout.com/docs/business-operations/prevent-fraud.md) solution, you can use rules and lists. --- ## Rules Rules take the form of an expression or collection of expressions. Each payment is assessed against a rule as either `true` or `false`. Each `true` / `false` decision point in the assessment journey is referred to as a branch. Branches determine how the payment is routed and the outcome. You can create rules using the following attributes defined by Checkout.com: - Library - Operators and functions, based on properties or metadata - [Properties](https://www.checkout.com/docs/developer-resources/codes/risk-property-codes.md) - Velocities Rules can reference: - Arrays and lists – for example, `:currency: IN ["EUR", "GBP", "USD"]` is assessed as `true` when the currency in the payment request matches any of the currencies provided in the array - Contextual information – for example, `Billing address is valid` - Metadata from payment requests – for example, `$customer_tier = "Gold"` - Payment request data – for example, `:amount_in_usd: > 1000` - Statistical data derived from your traffic – for example, `velocity(card_number, 30d, declined) > 1` ### Rule categories Rules fall into the following categories: | Rule | Summary | | --- | --- | | Address Verification Service (AVS) | The [AVS](https://www.checkout.com/docs/business-operations/prevent-fraud/verify-customer-addresses.md) is widely used in Canada, the UK, and the US to verify that the billing address the cardholder provided matches the address the issuer has on file.

This only applies to EU and US credit cards, where a billing address is provided. | | Custom rules | Combine conditions to better identify combinations of attributes and more effectively target fraud patterns. | | Mismatch rules | Identify when the details of a payment do not match. For example, the bank identification number (BIN) country and the cardholder's IP address are in different geographic locations. | | Processor routing rules | Specify the order in which to attempt different processors in the [`routing` object](https://api-reference.checkout.com/tag/Payments/#operation/requestAPaymentOrPayout!path=0/routing&t=request) in your payment request. | | Threshold amounts | Take a specific action based on the amount and currency of a payment, typically to manage exposure to fraudulent high-value orders. | | Velocities | Identify how often an attribute, or combination of attributes, occurs within a specific time time window. | | Verified information rules | Identify when information such as email, billing address, shipping address is valid or potentially fraudulent. | > **Information** > > You can unlock advanced custom rules, risk scores, velocities, and metadata with [Fraud Detection Pro](https://www.checkout.com/docs/business-operations/prevent-fraud/upgrade-to-pro.md). --- ## Velocities Velocities count transaction patterns within specified time windows to identify unusual or potentially fraudulent activity. The count starts at zero and increments with each instance. After the time window elapses, the count resets to zero. For example, the _Transaction count_ velocity rule checks when there are more than 10 attempted requests for a particular billing address within 24 hours: `velocity (billing_address, 24h, attempted) > 10` Fraud Detection offers the following velocity types: | Velocity type | Description | | --- | --- | | Standard velocity | Provides exact counts of transactions or amounts within the specified time window.

The values are precise and reflect the actual count of events. | | Relative velocity | Measures how many distinct values are observed for a particular attribute.

For example, how many unique cards are used with a specific email address.

The values are approximations, not exact counts, with a typical margin of error of around five percent. | > **Information** > > You can unlock [network velocity](https://www.checkout.com/docs/business-operations/prevent-fraud/upgrade-to-pro.md#Velocities) with Fraud Detection Pro. ### Example increments **Standard velocity** For example, if your rule counts transactions from a specific card within a one hour time window, and then re-sets to zero at the end of each time window, velocity increments as follows: | Time | Event | Velocity | | --- | --- | --- | | 9:00 AM | Transaction 1 | `0` | | 9:15 AM | Transaction 2 | `1` | | 9:30 AM | Transaction 3 | `2` | | 10:05 AM | Transaction 4 – First transaction in the reset time window | `2` | | 11:00 AM | No new transaction | `0` | | 11:30 AM | Transaction 5 | `0` | **Relative velocity** For example, if your rule counts unique cards used per email address within a one hour time window, and then re-sets to zero at the end of each time window, velocity increments as follows: | Time | Event | Velocity | | --- | --- | --- | | 9:00 AM | Email used with Card A | `0` | | 9:15 AM | Same email used with Card B | `≈1` | | 9:30 AM | Same email used with Card A again | `≈2`

Not incremented because Card A has already been counted | | 10:05 AM | Transaction 4 – First transaction in the reset time window | `≈2` | | 11:00 AM | No new transactions | `0` | | 11:30 AM | Same email used with Card A | `0` | ### Windows and intervals Shorter time windows (`5m`, `1h`, `3h`) update more frequently to capture rapid changes. They enable you to detect bursts of activity and respond rapidly. Longer windows (`24h`, `7d`, `30d`) update less often because the relative impact of individual transactions is lower. They enable you to identify patterns over time. Relative velocity, by contrast, enables you to detect unusual numbers of specific values appearing together. Transactions are grouped into intervals that correspond to the update frequency, rather than being tracked individually. The following windows and intervals are supported: | Window | Description | Approximate update frequency & interval | | --- | --- | --- | | `5m` | Five minutes | Every five seconds | | `1h` | One hour | Every 10 seconds | | `3h` | Three hours | Every one minute | | `24h` | 24 hours | Every 10 minutes | | `7d` | Seven days | Every 30 minutes | | `30d` | 30 days | Every one hour | For example, for a 24-hour time window with a 10 minute interval: - Transaction 1 at 10:03 AM falls into the 10:00–10:10 AM interval. - Transaction 2 at 10:07 AM falls into the same interval. - Both transactions leave the 24-hour time window together, when the last interval ends. ### Post-auth velocities Post-auth velocity properties are only counted when the post-auth strategy is assessed, as follows: - Attempted payments – Not counted if the payment declines before the post-auth stage - Declined payments – Only counted if the payment declines after the post-auth stage – for example `ChargeVoided` or `ChargeVoidDeclined` - Approved payments – Counted For example, see the `payment_account_reference` [card property](https://www.checkout.com/docs/developer-resources/codes/risk-property-codes.md#Card_properties). --- ## Create rules To create rules, you need the one of the following [user roles](https://www.checkout.com/docs/business-operations/use-the-dashboard/user-permissions.md): - Admin - Risk manager - A custom role with the `Create, edit, or delete rules` permission 1. Sign in to the [Dashboard](https://dashboard.checkout.com). 2. Go to _Fraud_ > _Strategy_ > _Rules_. 3. Select _Create rule_, and enter a rule name. 4. Select the relevant attributes from the _Library_, _Properties_, _Operators & Functions_, and _Velocities_ tabs. They appear in the _Rule expression_ field. 5. To test the rule, select _Check rule_. 6. When complete, select _Create rule_. ### Example rules | Rule name and syntax | Description | | --- | --- | | Email address used with more than three cards within 24 hours

`relative_velocity(card_number_per_email, 24h, attempted) > 3` | Counts the number of unique cards used for a given email address within 24 hours, and identifies if more than three different cards are used | | Device uses more than three email addresses

`relative_velocity(email_per_device, 24h, attempted) > 3` | Counts the number of unique email addresses used for a given device within 24 hours, and identifies if more than three different email addresses are used | | Bank identification number (BIN) declined more than 1,500 times in customer-initiated transactions (CITs) using a US card within three hours

`velocity(bin, 3h, declined) > 1500 AND :card_country: = 'US' AND :is_merchant_initiated: = false` | Counts the number of times the same BIN appears within three hours in all declined transactions, and identifies if it was all of the following:
1. More than 1,500 times
2. A US card
3. A CIT | | Card or cardholder attempts more than eight payments within one hour

`velocity(card_number, 1h, attempted) > 8 OR velocity(cardholder_name, 1h, attempted) > 8` | Counts the number of times a given email address and card appear within one hour in all attempted payments, and identifies if either count is more than eight times | | Card is declined more than five times within one hour

`velocity(card_number, 1h, declined) > 5` | Counts the number of times a card appears within three hours in all declined payments, and identifies if it's more than five times | --- ## Lists Lists are sets of values that can be referenced in rules. You can create trust lists and decline lists. > **Information** > > Matches within lists are case insensitive. ## Create trust lists A trust list allows payments that match a specified attribute to bypass all rules in your risk strategies. > **Note** > > Checkout.com may still decline payments that match attributes in your trust list due to global policies. You can add the following types of entries to trust lists: - Email address - Email domain - Payment IP To create trust lists, you need the one of the following user roles: - Admin - Risk manager - A custom role with the `Create, edit, or delete rules` permission 1. Sign in to the [Dashboard](https://dashboard.checkout.com). 2. In the _Business entity_ selector, select the client view. 3. Go to _Fraud_ > _Strategy_ > _Lists_. 4. Select the _Trust lists_ tab, and then the relevant entry-type tab. 5. Select _Add entry_, enter a value, and then select _Add_. --- ## Create decline lists A decline list is also known as a blocklist, which rejects payments based on specific attributes. If an attribute matches a list entry, it is automatically declined. Decline lists are different to decline rules, which are formulas that determine an outcome. For example, `amount > 1000 and card_country = Italy`. You can add the following types of entries to decline lists: - BIN – The first six to eight digits of the card number that identifies the issuer - Card – The 16-digit card number and expiry date - Email address – The customer's full email address - Email domain – The domain of the customer's email, which comes after the `@` symbol - Payment IP – The customers IP address - Phone – The customer's phone number To create decline lists, you need one of the following user roles: - Admin - Risk manager - A custom role with the `Decline high-risk payments` and `Create, edit, or delete rules` permissions 1. Sign in to the [Dashboard](https://dashboard.checkout.com). 2. In the _Business entity_ selector, select the client view. 3. Go to _Fraud_ > _Strategy_ > _Lists_. 4. Select the _Decline lists_ tab, and then the relevant entry-type tab. 5. Select _Add entry_, enter a value, and then select _Add_. Alternatively, to add a specific payment to a decline list: 1. Sign in to the [Dashboard](https://dashboard.checkout.com). 2. Go to _Payments_ > _Processing_ > _All payments_. 3. Select the relevant payment to view the _Payment details_ page. 4. On the _Payment details_ page, select _Decline list_. > **Note** > > Checkout.com also manages a global list of cards that have been declined by other Checkout.com merchants. > We automatically decline any card that has been declined by at least three other merchants. > **Information** > > You can use advanced [custom lists](https://www.checkout.com/docs/business-operations/prevent-fraud/upgrade-to-pro.md#Custom_lists) with Fraud Detection Pro. --- ## Next steps **[Build and test risk strategies](https://www.checkout.com/docs/business-operations/prevent-fraud/build-and-test-risk-strategies.md)** Build your test strategies, perform shadow testing to check their performance, and then migrate them to live. **[Integrate with Risk SDK](https://www.checkout.com/docs/business-operations/prevent-fraud/integrate-with-risk-sdk.md)** Integrate with a Risk SDK to maximize efficiency for customer-initiated payments. **[Optimize payment request data](https://www.checkout.com/docs/business-operations/prevent-fraud/optimize-payment-request-data.md)** Learn how to provide high quality data in your payment requests to improve the effectiveness of your integration. **[Monitor risk performance](https://www.checkout.com/docs/business-operations/prevent-fraud/monitor-risk-performance.md)** Monitor the performance of your Fraud Detection risk strategies.