Create risk rules and lists

Last updated: January 28, 2026

When building risk strategies for the Fraud Detection solution, you can use rules and lists.

Rules are pre-defined by Checkout.com and 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
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

Rules fall into the following categories:

Rule	Summary
Address Verification Service (AVS)	The AVS 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 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.

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.

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 with Fraud Detection Pro.

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`

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`

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

To create rules, you need the one of the following user roles:

Admin
Risk manager
A custom role with the Create, edit, or delete rules permission

Sign in to the Dashboard.
Go to Fraud > Strategy > Rules.
Select Create rule, and enter a rule name.
Select the relevant attributes from the Library, Properties, Operators & Functions, and Velocities tabs. They appear in the Rule expression field.
To test the rule, select Check rule.
When complete, select Create rule.

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: More than 1,500 times A US card 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 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.

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

Sign in to the Dashboard.
In the Business entity selector, select the client view.
Go to Fraud > Strategy > Lists.
Select the Trust lists tab, and then the relevant entry-type tab.
Select Add entry, enter a value, and then select Add.

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

Sign in to the Dashboard.
In the Business entity selector, select the client view.
Go to Fraud > Strategy > Lists.
Select the Decline lists tab, and then the relevant entry-type tab.
Select Add entry, enter a value, and then select Add.

Alternatively, to add a specific payment to a decline list:

Sign in to the Dashboard.
Go to Payments > Processing > All payments.
Select the relevant payment to view the Payment details page.
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 with Fraud Detection Pro.

Create risk rules and lists

Rules

Rule categories

Information

Velocities

Information

Example increments

Windows and intervals

Post-auth velocities

Create rules

Example rules

Lists

Information

Create trust lists

Note

Create decline lists

Note

Information

Next steps

Build and test risk strategies

Integrate with Risk SDK

Optimize payment request data

Monitor risk performance