Rules Reference

Rule processing and ordering

When creating a rule, the action it’s going to take determines the order in which it is processed. Each payment is evaluated against the rules you have created and performed in a specific order:

1. Allow: Rules that allow a payment to be processed. If a payment is allowed, it is not evaluated against any block or review rules.
2. Block: Rules that block a payment and reject it. If a payment is rejected, it’s not evaluated against any review rules.
3. Review: Rules that allow a payment to be processed but are then placed in review

If a payment should match a rule’s criteria, the respective action is performed and no further rules are evaluated against the payment. If a payment matches an allow rule, it’s processed normally–no block or review rules are subsequently evaluated, even if the payment would also meet their criteria. For instance, an example set of rules might be as follows:

• Allow payments less than $10
• Allow payments made within the US and with a risk level of normal
• Block payments where the risk level is high
• Block payments greater than $1,000
• Review payments made with a card issued outside the U.S.

Using the rules above, all payment less than $10 would be processed, regardless of their risk level or where the card used was issued. This is because the first rule allows the payment, so no further rules are evaluated. Similarly, a $1,500 payment made within the U.S. with a normal risk level would also be allowed, despite the rule to block payments over $1,000. This is because of the second rule in the list, allowing payments made within the US and a normal risk level. Once a particular rule is triggered, no further rules are evaluated.

Rule structure

Rules are constructed using two components: the action it should take and the condition to evaluate:

{action} if {condition}

In practice, a rule to block all payments over $1,000 would appear as:

Block if :amount_in_usd: > 1000.00

• The action is Block
• The condition is :amount_in_usd: > 1000.00

Actions

A rule can perform one of three actions with a payment that meets its criteria, which are processed in this specific order.

Allow

This rule action determines when a payment of a certain criteria should always be allowed, regardless of Stripe’s evaluation and any other rules the payment might match. When a payment matches the criteria in an allow rule, it is processed normally by Stripe and has no further rules evaluated against it. Even when Stripe proceeds with a payment it may nonetheless be declined by the issuing bank.

Block

This specifies when a payment should always be blocked by Stripe. If a payment matches the criteria in a block rule, the payment is rejected and no further rules are evaluated.

Review

There might be certain types of payments you want to allow, but still take a closer look at. With review rules, you can place payments in review. This is especially useful to manage payments that aren’t particularly common, such as those with a larger than usual amount or from a country that you don’t often ship to. These payments are still processed, and the customer charged, but you have an additional opportunity to review the order to make sure there are no signs of fraud.

Conditions

If a payment matches a rule’s condition, the corresponding action is taken. A basic condition is, itself, made up of three parts:

[attribute] [operator] [value]

• Attribute: The attribute of a payment (e.g., the amount or type of card)
• Operator: The arithmetic that compares the attribute to the value (e.g., greater than or not equal to)
• Value: The criteria you wish to use (e.g., 100.00 or debit)

Combining both the action and condition together, the structure of a rule is:

{action} if {[attribute] [operator] [value]}

There are four types of conditions that exist, depending on the attribute type:

• [string_attribute] [operator] [string_value]
• [country_attribute] [operator] [country_value]
• [numeric_attribute] [operator] [numeric_value]
• [boolean_attribute]

Certain attributes can also be used as a corresponding value within a condition. For instance, you can create a rule to block payments where the country the card was issued does not match against the country the payment was made, using the following attribute and value:

Block if :card_country: != :ip_country:

String attributes

These contain any combination of characters. String attributes and values most commonly represent a piece of text, such as a card’s brand (e.g., visa, amex) or risk level (e.g., elevated). These can be used in rules to allow payments only from a particular country, or block payments made with prepaid cards.

Metadata attributes

These attributes are derived from the metadata you have attached to your payments. Metadata attributes operate in the same manner as string attributes with the difference that they are case-sensitive. You can use these attributes when creating Radar rules, thus enabling you to write rules against any custom business attributes you have passed to Stripe via the metadata field attached to your payments.

Metadata attributes are written in the following structure:

::[metadata attribute name]:: [operator] [metadata_value]

Suppose we have payments with the following key-value data stored in the metadata field:

A rule can be written to place payments that match the following criteria into review.

Review if ::Item ID:: = '41523'

You can also write rules using both metadata attributes as well other supported attributes mentioned in this document. Only place a payment in review if Category ID matches “groceries” and amount of the payment exceeds US$1,000.

Review if ::Category ID:: = 'groceries' and :amount_in_usd: > 1000

Metadata attributes also support the IN operator to match against multiple values. Only place a payment in review if Category ID is one of “groceries”, “electronics” or “clothing” categories.

Review if ::Category ID:: IN ('groceries', 'electronics', 'clothing')

Escapes

Metadata attributes have to be written with surrounding double colons :: to identify them as such, if your payment metadata name contains the : character, you can use \ as an escape character to write your rules:

Review if ::Inventory\:\:ItemID:: = '41523'

Country attributes

These makes use of two-letter country codes to represent a country, such as US for United States or CA for Canada. Country attributes operate the same as string attributes, the only difference being that the value must be a country code.

Numeric attributes

As these only contain numbers, they support more operators than string attributes and values. A payment’s amount is one example of a numeric attribute, and a rule can be created to perform an action should the amount be higher, lower, equal, or not equal to the amount you specify.

For numeric attributes that are counts over time windows—for example, charge_attempts_per_ip_address_hourly (the number of charge attempts from the payment’s IP address in the hour preceding the payment in question)—the count does not include the payment currently being processed. charge_attempts_per_ip_address_hourly thus has a value of 0 for the first charge attempt from a given IP address in an hour (since there were no attempts from the IP in the preceding hour), a value of 1 for the second attempt (since there was one preceding attempt), and so on.

Boolean attributes

A Boolean attribute simply represents whether a particular attribute is true. Unlike string and numeric attributes, there are no operators or values to use. You can use a Boolean attribute to block payments that have been made with a disposable email address, or place payments in review that were made with an anonymous IP address.

Post-authorization attributes

A post-authorization attribute (e.g. :failed_cvc_verification:, :failed_address_zip_verification:, or :failed_address_line1_verification:) requires Stripe to exchange data with card-issuing banks as part of the authorization process. For this reason, rules that use post-authorization attributes will be executed after rules that don’t use them. (This won’t affect whether a charge is blocked or not, but may impact which rule the charge is blocked by.)

Also note that if you use a post-authorization attribute in a rule, your customer’s statement may temporarily show an authorization even if the charge is ultimately blocked; the authorization will generally disappear after a few days.

Supported attributes

The payment attributes listed below are supported in rule definitions.

The email_domain and is_disposable_email attributes make use of an email address found in any of the following fields:

• The receipt_email of the payment
• The description of the payment
• The name of the card (if an email address has been provided as the cardholder name)
• The email of the customer that the payment was created on
• The description of the customer or payment

Converted amounts

When using amount_in_xyz, Stripe automatically determines the converted amount of any payment when checking if the amount matches your chosen criteria. For example, if you create a rule using amount_in_usd to block all payments greater than $1,000 USD, Stripe would block a £900.00 GBP payment as its equivalent converted USD value would be approximately $1,200.00.

Operators

A condition’s operator denotes the comparison between the payment’s attribute and the value you provide. There are different operators available, depending on the type attribute being used.

Missing attributes

Typical rule conditions refer to attributes set on every payment, such as :card_country: (which is set on every card-based charge) or a metadata attribute you always send with your payment requests. However, there are scenarios in which an attribute might be missing, for example:

• You have different checkout flows on your site, and some of them do not collect customers’ email addresses

• You’ve only recently started using Stripe.js, and so :ip_country: is available on new payments, but not available on historical payments (which we search when previewing rules)

• For some of your payments, a bug in your integration fails to set an expected metadata key

How rule conditions evaluate missing attributes

Consider the rule Block if :email_domain: = 'definitelyfraud.com'. If you didn’t collect the customer’s email address, the :email_domain: attribute would be missing, and—as you might expect—the rule condition would not match the payment.

Now consider the rule Review if :email_domain: != 'definitelysafe.com'. If the :email_domain: attribute is missing, this rule also does not match the payment. This result might seem a bit surprising, as a missing value is indeed not the same as 'definitelysafe.com'. But we’ve found it’s best to interpret != 'definitelysafe.com' to mean “the attribute has some value other than 'definitelysafe.com',” which a missing attribute does not satisfy.

More generally: any comparison (e.g., =, !=, >, <) of a missing feature against another static value or feature (missing or present) always returns false.

Explicit handling with the is_missing function

If you would like to explicitly check for the existence of an attribute or metadata attribute, use the is_missing function. Provide this function with the attribute or metadata key that may be missing.

For example, you could write a rule to match all payments where you do not have access to a customer’s email address:

• Review if is_missing(:email_domain:)

Or you might write a rule to match all payments for which a certain metadata attribute is set:

• Review if !(is_missing(::foo::))

The is_missing function can also be used in OR or AND conjunctions:

• Review if is_missing(:email_domain:) OR :email_domain: IN ('yopmail.net', 'yandex.ru')

Complex conditions

You can build complex conditions by joining together basic conditions using the operators AND, OR, and NOT. You can also use their symbolic equivalents: &&, ||, and ! respectively.

Similar to programming languages such as C, Python, and SQL, Stripe supports standard operator precedence (order of operations). For instance, the complex condition:

{condition_X} OR NOT {condition_Y} AND {condition_Z}

is interpreted as:

{condition_X} OR ((NOT {condition_Y}) AND {condition_Z})

Sub-conditional grouping within complex conditions is also supported using parentheses. For instance, the prior example can be amended to explicitly change the evaluation order of sub-predicates:

({condition_X} OR (NOT {condition_Y})) AND {condition_Z}

{condition_X} OR NOT ({condition_Y} AND {condition_Z})

By using parentheses in different locations, each of these complex conditions lead to different results.