Expression syntax

The expressions used in rules follow a lean syntax inspired by spreadsheet formulas. Each expression is composed of, at minimum, a variable, an operation, and a value.

$merchant_id == "XYZ"

The expression above is true when the merchant ID equals "XYZ".

Variables

Every variable starts with $. The available variables depend on the event type being evaluated.

Variable	Content	Type	Example
$amount	Total payment amount	Decimal	100.12
$card_bin	First 6 to 8 digits of the PAN (BIN/IIN)	Text	"44332211"
$card_issuer_country	Card issuer country (ISO 3166-1 alpha-2)	Text	"BR"
$card_last_four	Last four digits of the card	Text	"1234"
$device_fingerprint_id	Device fingerprint	Text	"xyz"
$device_ip_address	Device IP address	IP address	"200.123.10.2"
$device_user_agent	Device User-Agent	Text	"Mozilla/5.0"
$merchant_id	Merchant ID	Text	"store-1234"
$metadata_[key]	Metadata sent via API	Text	"value"
$score	Risk score calculated by the platform (0.00 to 1.00)	Decimal	0.75
$user_email_domain	User’s email domain	Text	"gmail.com"
$user_id	User ID	Text	"customer-1234"
$user_profiles	User’s payment profiles (available only with the count function)	Collection	N/A

Operations

Operation	Meaning
==	Equality
!=	Inequality
>	Greater than
>=	Greater than or equal to
<	Less than
<=	Less than or equal to
in	Belongs to a collection
not in	Does not belong to a collection

Values

The value compared against a variable can be text or a number:

• Text: always in double quotes, like "XYZ". Single quotes and unquoted text are not accepted.
• Number: written without quotes, using a period as the decimal separator, like 1000 or 99.01.

Since all text is double-quoted, values such as an IP, a date, or a word used in the syntax itself (for example, in) also need the quotes to be treated as text.

To check whether a variable is empty, compare it with null (without quotes) using == or !=:

$device_fingerprint_id == null

The expression above is true when the event has no device fingerprint. Use != for the opposite case, when the variable has some value.

Functions

concat

The concat function joins several values into a single text, which can be compared against a value. Each argument is a variable ($variable) or fixed text, separated by commas:

concat($user_id, "-", $merchant_id) == "customer-1234-store-1234"

The expression above is true when the combination of the user ID and the merchant ID, joined by a hyphen, results in "customer-1234-store-1234".

Considerations about the joined values:

• Variables without a value are treated as empty text.
• Numeric values are converted to text in their original form (for example, 99.01 and 0.9).

Combining expressions

Use and and or to combine expressions. and takes precedence over or: in a combination without parentheses, the parts joined by and are evaluated first. So A and B or C is equivalent to (A and B) or C.

Use parentheses to group expressions and change this precedence:

($amount > 1000 and $user_email_domain == "gmail.com") or $card_issuer_country != "BR"

Lists

Lists configured under Settings > Lists are available as collections. For example, to check whether a customer is on a quarantine list:

$user_id in @quarantined_customers

You can also write the collection directly in the expression, in square brackets with the values separated by commas. For example, to check whether the card issuer country is not among the supported countries:

$card_issuer_country not in ["BR", "AR", "CL"]