Create risk rules and lists

Last updated: August 20, 2025

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	Custom rules enable you to combine conditions to better identify combinations of attributes and more effectively target fraud patterns.
Mismatch rules	You can configure mismatch rules for when the details of a payment do not match. For example, the bank identification number (BIN)'s country and the cardholder's IP address are in different geolocations.
Processor routing rules	You can add rules to the `routing` object in your payment request to specify the order in which to attempt different processors.
Risk scores	Risk scores indicate Checkout.com's assessment of the level of risk for a given payment. They are based on our machine learning models, which are trained on all of our payments and fraud data. Payments receive a score between `0` and `100` to indicate the risk level as follows: `0` – `5` – Low risk `5` – `15` – Medium risk `15` – `100` – High risk Note From October 1, 2025, risk scores are only available with Fraud Detection Pro.
Threshold amounts	You can set threshold amounts to take a specific action based on the amount and currency of a payment, typically to manage exposure to fraudulent high-value orders.
Velocity rules	Velocities check how often a single attribute occurs within a specific time frame and take specific actions accordingly. You can set them for a range of time frames, including daily, weekly and monthly. After the time frame elapses, the velocity count resets to zero and starts again. For example, the Transaction count velocity rule checks how often a single attribute occurs within a time frame: `velocity (billing_address, 24h, attempted) > 10` occurs when there are more than 10 attempted requests for a particular billing address within 24 hours.
Verified information rules	Verified information rules check if information such as email, billing address, shipping address is valid or potentially fraudulent.

Information

You can unlock advanced custom rules, risk scores, velocity rules with Fraud Detection Pro.

You need the Admin user role or 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

Metadata can include arrays and lists. For example, $product_code IN @high_risk_product_list uses the $product_code metadata to check the @high_risk_product_list custom list.

To reference a metadata field in a rule, prefix the key with $. For example, with the previous payment request example, the following rule is assessed as true:


1$my_key in ['1', '42', '3']

Alternatively, you can pass metadata as an argument to any function that takes in a string, number, or boolean. For example, you can assess the boolean value of a metadata property:


1not($my_boolean)

You can also use metadata values in calculations:


1convert_from_usd($tip_amount, gbp) >= $suspicious_tip_amount

Information

Metadata keys and values are case insensitive.

Lists are sets of values that can be referenced in rules. You can create trust lists, decline lists, and custom 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 a trust list:

Sign in to the Dashboard.
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 a decline list, you must have one of the following user roles:

Admin
Risk manager
A custom role with the Decline high-risk payments permission

Sign in to the Dashboard.
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.

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

Note

Information

Create rules

Example rules

Reference metadata

Information

Lists

Create trust lists

Note

Create decline lists

Note

Information

Next steps

Build and test risk strategies

Integrate with Risk SDK

Optimize payment request data